Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: Good ways to capture institutional knowledge?

news.ycombinator.com

Post reply on HN
Print view View original

181–190 of 220 posts

Re: Ask HN: Good ways to capture institutional knowledge?

#181

Post by m0zg »

MaxBarraclough wrote: post #120
m0zg wrote: post #89

Earlier quoted context omitted.

This is what I do. And if the Markdown file is not near the code in question, it's a 100% guarantee you've wasted time writing it because nobody is going to read it. I also write comments first when writing complex code and then fill in the code in between. More than once this helped more than any documentation could, because people do not read documentation if they can avoid it, and avoid it they'll try.

> if the Markdown file is not near the code in question, it's a 100% guarantee you've wasted time writing it because nobody is going to read it. This ignores hyperlinks. Why not use in-code comments for explaining nuts-and-bolts matters (for example, to explain strange-looking platform-sensitive code using #ifdef ), and use links to wiki pages for descriptions of high-level design decisions?

I meant that I do documentation on the side, not in code. In code, I do human readable comments (using a restricted subset of markdown) where things would otherwise be very difficult to understand.

All of this applies uniformly for the code I write for others, as well as code I write for myself.

Re: Ask HN: Good ways to capture institutional knowledge?

#182

Post by rtx »

schmichael wrote: post #156
herval wrote: post #74

Earlier quoted context omitted.

How do/could you quantify the benefits of this culture? I frequently manage groups of “move fast & break things” folks, and RFCs/design docs/etc are a very hard sell (in particular when teams are fully local)

Quantifying human processes is not one of my strengths, however these are some situations a culture of writing helps avoid: - Fear to go on vacation or take sick days because you'll miss live decision making - Paternity/Maternity or other extended leave requiring a second onboarding upon return - Animosity when left out of a lunch or beer where a design was discussed or decision was made - Cabals of knowledge holders…

Do you write about or teach these things.

Re: Ask HN: Good ways to capture institutional knowledge?

#183

Post by heavenlyblue »

fsloth wrote: post #164
heavenlyblue wrote: post #148

Earlier quoted context omitted.

There is a reason why everyone uses LaTeX (or similar) when it comes to professional content delivery - it actually saves you time not fighting the editor.

There's no reason why internal readmes should be of 'professional quality'. It's nice, but a low barrier of entry to explain something non-trivial is more important than nice layout, IMO. "Everyone" is not using LaTeX.

Yeah. Except WYSIWYGs take way more time to do anything non-trivial.

This Friday I had spent about 15 minutes trying to put an editor cursor within an empty code block in Confluence. Is that a joke? Do you know how I fixed that? I copied a non-empty block from another paragraph and then edited it.

It would take me or someone else half a second to do that in Markdown/Wiki/LaTeX.

Re: Ask HN: Good ways to capture institutional knowledge?

#184

Post by sytelus »

tehlike wrote: post #64
sytelus wrote: post #11

Simple rule: Require that new hires should be able to become productive without having to talk to anyone (physically or electronically). The rest will fall in place.

Terrible advice. Part of the knowledge of a large system is due to having discussions with others.

Discussions are good for critic and improvements. But to get up and running i.e. setting up your environment, building things, understanding existing design, running from source, finding roadmaps, getting list of open issues and setting up for debugging should not require talking to anyone.

Re: Ask HN: Good ways to capture institutional knowledge?

#185

Post by schmichael »

rtx wrote: post #182
schmichael wrote: post #156

Earlier quoted context omitted.

Quantifying human processes is not one of my strengths, however these are some situations a culture of writing helps avoid: - Fear to go on vacation or take sick days because you'll miss live decision making - Paternity/Maternity or other extended leave requiring a second onboarding upon return - Animosity when left out of a lunch or beer where a design was discussed or decision was made - Cabals of knowledge holders…

Do you write about or teach these things.

Ironically: no. It's something we discuss regularly at HashiCorp and, as you might expect, have a lot of internal resources (docs, videos, training) around.

I haven't looked at it myself, but I know Google just released some training materials for technical writing: https://developers.google.com/tech-writing

Re: Ask HN: Good ways to capture institutional knowledge?

#186

Post by MaxBarraclough »

AmericanChopper wrote: post #175
MaxBarraclough wrote: post #121

Earlier quoted context omitted.

> major shortcoming is that it’s not accessible enough for non-technical teams to maintain At the risk of just mirroring my comment above: Low-level nuts-and-bolts documentation can't be accessible to non-technical people, by nature. Documentation of high-level designs are another matter. Why not use a wiki for the documentation of high-level decision-decisions? A wiki can be accessible to non-technical staff, and it…

> Why not use a wiki for the documentation of high-level decision-decisions? Because if you create different solutions to meet the publishing preferences of different groups inside the organisation, then I don’t think you’re meeting the goal of institutionalizing the knowledge. If a consumer wants to find some documentation, you don’t what their first step to be trying to find the system it’s stored in. Especially in…

> Because if you create different solutions to meet the publishing preferences of different groups inside the organisation, then I don’t think you’re meeting the goal of institutionalizing the knowledge.

High-level project descriptions don't belong in code. It's a different beast, and doesn't belong in the repo alongside the implementation. Non-technical users probably shouldn't even have repo access.

In-code comments, on the other hand, can't reside anywhere else.

> If a consumer wants to find some documentation, you don’t what their first step to be trying to find the system it’s stored in.

They don't need to look. That's what hyperlinks are for.

I'm not sure if you mean end-user here, or the consumer of a library.

If an end-user wants documentation, that means it's high-level documentation, not nuts-and-bolts documentation on the workings of code. A wiki is a fine solution for this. A non-technical end-user has no business exploring the repo.

If it's someone looking into how to use your library, the distinction is still there. If I want to know what Qt is, I look it up on Wikipedia. If I want to learn about a specific concept, I look for a documentation page like this [0]. In neither case would source-code comments be a reasonable choice.

> Especially in very large organisations, where you could easily end up operating quite a few different publishing platforms.

Maintaining a stable intranet wiki is no great challenge.

> SharePoint is the closest things I’ve seen to a one-size-fits-all solution. But SharePoint is rather terrible to use.

For UI reasons I'd go with a wiki over SharePoint, but they're similar in principle: documentation lives in the intranet, each document has a URL, and documents are mutable. They can coexist if they need to: use hyperlinks.

I'm not sure a one-size-fits-all solution is a good idea in the first place. A legal document about a project is going to end up as a .pdf, and doesn't belong on a wiki. On the other hand, technical documentation like [0] should be handled in a 'web-first' way, such as with a wiki.

Perhaps if SharePoint's document-editing were more like a plain old wiki, I could be convinced that it's a reasonable one-size-fits-all solution. (Although in a sense it's doing several things.)

[0] https://doc.qt.io/qt-5/layout.html

Re: Ask HN: Good ways to capture institutional knowledge?

#187

Post by [deleted] »

onion2k wrote: post #107
Too wrote: post #68

Automate everything that can be automated. Avoid setting up things using GUIs. Starting a set of services should be as simple as "docker-compose up", building should be as simple as "make", checking out the code should be as simple as "git clone", etc. You shouldn't need a shitload of wiki checklists that describe how to install dependencies and how to check out all the git-directories with correct versions relative…

That's good technical advice but I don't think it works as far as knowledge capture goes. There are two problems. Firstly, it fails to solve the problem of actually capturing knowledge. In fact, if anything, you're suggesting that knowledge of the systems and processes shouldn't be necessary in order for the business to function and that building a black box that "just works" is good enough. The problem with that is…

[deleted]

Re: Ask HN: Good ways to capture institutional knowledge?

#188

Post by mooreds »

ndespres wrote: post #161

At each of my last 3 jobs I've been a strong advocate for tracking knowledge in a Wiki. We've used MediaWiki and Confluence, and both worked well. It helps if everyone does their part to contribute, which doesn't always mean everyone has to write. Some people can dictate what they know. Some can provide screenshots. Sometimes just getting someone to leave a comment with a correction is enough. I like to start with st…

> We have a regular pager rotation for emergencies, so if you get an overnight call to work on something and can't find the information about it, you start to realize how important the docs are. That has been a big motivator in getting people to update docs about the things they know. If you don't want a call overnight, make sure there's nothing that isn't in the wiki!

I had a co-worker write about the importance of documentation to folks who are on call, and why it is hard to get it right: https://www.transposit.com/blog/2020.02.26-rewarding-documen...

Re: Ask HN: Good ways to capture institutional knowledge?

#189

Post by etxm »

I have found Architecture Decision Records to be great for this.

They capture why a decision was made and the context/options at the time. They also provide an immutable linear log of decisions which is nice for on boarding.

https://github.com/joelparkerhenderson/architecture_decision...

Re: Ask HN: Good ways to capture institutional knowledge?

#190

Post by zmj »

JohnBooty wrote: post #163
duckmysick wrote: post #160

I noticed a lot of suggestions in this thread assume you want to capture the institutional knowledge related to coding and software: - comments in the source code - commit messages - readme - code review - pair programming - variable naming and refactoring Which is all great, but at the same time narrow. What if I want to capture institutional knowledge when it comes to accounting, HR, PR, management, negotiations, s…

comments in the source code This is an unpopular opinion, but I fervently agree with it. It one of the most powerful ways to keep a codebase comprehendible. Some folks say, "That's what commit messages are for." Bullshit. When people say that, I suspect they've never worked on anything other than prototypes or toy projects. Good commit messages are a must, but they don't scale well when it comes to long-lived project…

> Some folks say, "That's what commit messages are for." Bullshit. When people say that, I suspect they've never worked on anything other than prototypes or toy projects. Good commit messages are a must, but they don't scale well when it comes to long-lived projects.

Yep. I've seen codebases that have migrated source control and issue trackers multiple times - sometimes migrating history, sometimes not. The only ancient knowledge that has survived is the code comments.

Post reply on HN