Add e2e tests and design docs for code repos.
Ask HN: Good ways to capture institutional knowledge?
131–140 of 220 posts
Re: Ask HN: Good ways to capture institutional knowledge?
#132A trick I've used effectively is to have a "doc of docs" - a document that tells you where all the other documents for a project or team live. You can do this as a wiki page or a Google Doc. The important thing is that the answer to the question "where's the documentation for X" should ALWAYS be "it's in the doc-of-docs". Then you can take it a step further: you can say "it's in the doc-of-docs... and if it isn't, wh…
I like this “master read me” approach and try to also reference the lord of the rings poem to both try to make documenting fun and to explain the intent.
Three Docs for the Product-kings under the sky, Seven for the Dev-lords in their halls of stone, Nine for Mortal Men doomed to die, One for the Dark Lord on his dark throne In the Land of Mordor where the Shadows lie. One Doc to link them all, One Doc to find them, One Doc to bring them all, and in the darkness bind them, In the Land of Mordor where the Shadows lie.
Re: Ask HN: Good ways to capture institutional knowledge?
#133Earlier quoted context omitted.
I don't know what the infatuation with markdown is beyond web publishing. Wysiwyg documents have been a solved problem for decades. Use what works on your platform. Markdown is fine until you realize you would like to have figures, images and tables. I don't want to spend my time over trite details of a text based markup when I could spend it actually productively. At that point it's way over easier to use a text pro…
Wysiwyg document tools aren't applicable to comments in source. You can't have images in source, but if you really need it you could add an ascii-art-style table. There are tools to generate these, such as https://ozh.github.io/ascii-tables/
This was not about inline documentation in source, but about separate readmes.
If a hand typed ascii graphic does not suffice for code comment embedded docs, then it would be better to include separate docs altogether.
Re: Ask HN: Good ways to capture institutional knowledge?
#134There are far better tools for managing knowledge than wikis. Check out Bloomfire hhtps://www.bloomfire.com
They offer one such solution. You just upload documentation or type into the platform directly and every word in the document is searchable. From the site it looks like they even transcribe video and audio files and make them searchable as well. I know someone who has used it and loves it. Just to say, there are tools built for this....
Re: Ask HN: Good ways to capture institutional knowledge?
#135Learn how large-scale open source projects are managed and governed. Set up a team culture that could support remote working, even though teams are at this moment co-located. Can your team keep generating the same output even when they don‘t see each other everyday holding meetings? Such teams tend to leverage more async and written communication, write more complete, comprehensive documentation.
A good code review culture also improves knowledge sharing: We sometimes have two paragraphs of explanation in a pull request that changes one line of code. Those pull requests are forming a part of our institutional knowledge base and they are oftentimes referred during future conversations about past decisions.
The team should understand that spending a bit time today to write things down will save much more time in the future when the same thing has to be explained again and again. Also the team should be encouraged to spend this time on writing documents and not punished because of not starting with the next game-changing product feature.
Re: Ask HN: Good ways to capture institutional knowledge?
#136We find that Confluence + JIRA is a very effective way to pass knowledge around.
Re: Ask HN: Good ways to capture institutional knowledge?
#137For my personal use I create detailed "How To" documents that detail the exact steps required to do something non-trivial. Others have found them useful when I posted them on Confluence.
Re: Ask HN: Good ways to capture institutional knowledge?
#138For process documentation (eg, not code docs), we use a company shared Google Drive folder with subfolders broken down by department (sales, marketing, support, finance, general management, hr, etc) and within each we have documents and checklists that serve as both documentation and quality controls for our most critical business processes.
We have videos, slides, spreadsheets, docs - we always try to use the best format for the job.
It's not perfect but you're right in that it has a huge impact on the efficiency of certain processes and therefore, scalability.
Re: Ask HN: Good ways to capture institutional knowledge?
#139Mandatory vacation. This is something that the finance industry has used for a long time to guard against fraud -- it's hard to cover up something if someone else has to do your job for two weeks straight at some point -- but it also serves as a mechanism for requiring you to cross-train people. Two weeks of paid vacation where the company isn't allowed to email them or call them for help: I guarantee that documentat…
I worked in the finance industry and took the mandatory 2 week vacation and dealt with my coworkers taking the mandatory 2 week vacation. We didn't write any documentation or have any internal wiki or anything like that, and everything seemed fine. I also find it pretty questionable that someone couldn't write a computer program that can embezzle unattended for two weeks. You don't use your own credentials, you stick…
> We didn't write any documentation or have any internal wiki or anything like that, and everything seemed fine.
Just evidence that documentation != institutional knowledge. It's not actionable knowledge if no one reads it.
Re: Ask HN: Good ways to capture institutional knowledge?
#140[deleted]