Ask HN: Good ways to capture institutional knowledge?

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 stub articles and allow them to grow organically, without harping on folks about it.

Often there are many ways that changes are communicated (for example, an email to the NOC team to advise of systems being decommissioned, an email to the helpdesk to advise of new support procedures, etc). To some people, that email is the documentation. I know that if I want it captured in the knowledge base, that email is my cue to transpose the notification email into documentation that can be referenced later.

My current job is doing sysadmin support for a consultancy, so there are lots of clients and lots of other people doing this work. 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 use plugins to help point out when content might be out of date, and guide people to archiving out-of-date docs, or to update them. I regularly refer to Stewart Mader's great book Wikipatterns and its list of patterns/anti-patterns to help with wiki adoption and behavior. http://stewartmader.com/wikipatterns/ The book is a great read and covers a lot of your questions, especially skeptics and opponents, and how to address them.

    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 projects. Think of a source file that's had many dozens or hundreds of commits and refactorings. Tracking down the original author's intent can be very difficult - especially when the original commit doesn't reference what's happening on line 78 or whatever. Especially when there are dozens of such oddities in a single file.

Some other folks also say, "Good code is self-describing." Again, bullshit. Maybe if you're writing code in a vacuum. But code gets weird and messy where it interacts with other things that are outside your control. I can read your code and see what it's doing. But your code cannot tell me the "why." The kludges you implement to work around bugs in other libraries/browsers/APIs are NOT comprehensible without some contextual information about the bug you're trying to solve. Ditto for all the weird business logic that creeps into applications. Why aren't we charging sales tax on Topeka on Tuesdays? Tax law? Were we running some special promotion? Did our vendor in Topeka already collect sales tax in some other part of the process? A quick comment can save the next maintainer hours of wondering.

So, my rules are....

1. Stick a comment in there if you are implementing a kludge/workaround based on some external thing. Wrote your own CSV parser because the one in the standard library is broken? OK, tell me that so that I know this was a conscious choice and not a matter of you simply not knowing that the standard library existed.

2. Stick a quick comment in there if you are implementing business logic. Even if your comment is simply "Implement Bob's marketing idea for the job fair" that would at least give me something to go on five years from now when I'm wondering if I can delete that bit of code.

3. No need to document basic stuff. Retrieving some records from the DB? Writing to a file? No problem. Assume the person reading your code is a competent programmer. No need to describe that stuff.

I agree. Typos fixes and cleanups don't need this. The code + tests + documentation + issue link format should be for actual changes, not minor cleanups.

>The only solution would be for everything (every meeting and decision) to be rigorously documented with outcomes and justifications //

Action focussed minutes?

The best is the enemy of good here.

When I manage engineers, I insist on people having the old-fashion pen and paper notebooks: not scratch paper; not pads; not post-it notes. Simple 5 by 7 grids. During my weekly one-on-ones, I encourage people to make one or two positive changes:

* jot down any odd term they run across so they can google 'strangeNewTerm slides' later and batch through them all * write a quick note on any error taking over twenty minutes * go back and read their notebook here and there

People do use the notebooks, do record the information, do get sick of writing and do start reaching out for other ways to record information. I allow people to use Wikis, markup files, documents, or a mishmash: people are more likely to work on their own idea. I do insist that documentation be in source control and have 'section last updated' dates. Eventually, I encourage someone to maintain a master index of where non-code documentation is found.

The hard part is getting people not to document too much. Every document has a maintenance load, much like every line of code. It is far better to have an up-to-date hint like "TPS reports need cover pages per YoyoDyne contract, 3/2004" than volumes of out-of-date procedures, one of which mentions the YoyoDyne contract on page 37.

One totally different tact: new developers get assigned to the source code control review. That is, they look at the new commits; run the new code, update the project/company specific dictionary with any new terms; give the tests a careful reading and add to them; and write down any question. New developers quickly become familiar with the code base that is most likely to change.