TE
TechEcho
Home24h TopNewestBestAskShowJobs
GitHubTwitter
Home

TechEcho

A tech news platform built with Next.js, providing global tech news and discussions.

GitHubTwitter

Home

HomeNewestBestAskShowJobs

Resources

HackerNews APIOriginal HackerNewsNext.js

© 2025 TechEcho. All rights reserved.

Ask HN: How do you go about documenting tribal knowledge?

5 pointsby p33pover 6 years ago

4 comments

tonygrueover 6 years ago
For me depends on what the knowledge is.<p>About Code: The only way I&#x27;ve found that works is comments in the code itself (or docs generated from code annotations).<p>Processes: Playbooks and Automation. Playbooks - DropboxPaper&#x2F;Google docs that anyone can edit with things like &quot;How to Build and Push XYZ Component&quot;, &quot;What to do when the XYZ Server stops responding&quot;. Automation - When feasible turn the most used playbooks (or pieces of them) into scripts&#x2F;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&#x2F;unused tools, so it doesn&#x27;t feel like a wasteland.<p>Knowledge on how we do things: You don&#x27;t want to write docs about &#x27;how to do XYZ&#x27;. It will quickly be out-of-date and it&#x27;ll be horribly micromanagey. But if you and your team collaborative define and document your team values or project&#x2F;codebase&#x2F;module principles, I&#x27;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.
muzaniover 6 years ago
Just keep everyone in constant communication with one another. I find Slack + remote work is the best at this.<p>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&#x27;s not too hard to train someone for the post either; 1-2 months is long enough.<p>Formal documentation isn&#x27;t so great because it&#x27;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.
sethammonsover 6 years ago
&quot;write it down.&quot; Runbooks, code comments, test cases, etc. Also, avoid silos: pair programming, knowledge sharing sessions, demos, etc.
gcb0over 6 years ago
hire better* people to add to the mix. the problem will eventually solve itself.<p>you can&#x27;t force knowledge hoarders to change. learned that the hard way.<p>* better as in who like to share knowledge