Ask HN: How do you go about documenting tribal knowledge? - p33p
======
tonygrue
For me depends on what the knowledge is.

About Code: The only way I've found that works is comments in the code itself
(or docs generated from code annotations).

Processes: Playbooks and Automation. Playbooks - DropboxPaper/Google docs that
anyone can edit with things like "How to Build and Push XYZ Component", "What
to do when the XYZ Server stops responding". Automation - When feasible turn
the most used playbooks (or pieces of them) into scripts/tools. Make them the
default way of doing things; and any time a break is discovered, fix the tool
instead of working around it. Remove outdated/unused tools, so it doesn't feel
like a wasteland.

Knowledge on how we do things: You don't want to write docs about 'how to do
XYZ'. It will quickly be out-of-date and it'll be horribly micromanagey. But
if you and your team collaborative define and document your team values or
project/codebase/module principles, I've found you can onboard people quickly
and reduce communication. They key here is referencing to the documents when
you make a decision guided by them, to keep the docs fresh in peoples minds.
And to regularly update the docs.

------
muzani
Just keep everyone in constant communication with one another. I find Slack +
remote work is the best at this.

Another option is someone officially employed for this, i.e. a system analyst.
Their job is just to know how everything comes together and point out what
existing documentation exists, which parts of the system are flawed, what has
been tried and failed, why it failed. It's not too hard to train someone for
the post either; 1-2 months is long enough.

Formal documentation isn't so great because it's difficult to write and often
you need some meta to help you find where the right documents are stored. But
you do need a combination of written and oral documented knowledge.

------
sethammons
"write it down." Runbooks, code comments, test cases, etc. Also, avoid silos:
pair programming, knowledge sharing sessions, demos, etc.

------
gcb0
hire better* people to add to the mix. the problem will eventually solve
itself.

you can't force knowledge hoarders to change. learned that the hard way.

* better as in who like to share knowledge

