Ask HN: How does your team handle knowledge documentation?

I would suggest adding the use of Doxygen to your projects. It supports Markdown files as well as Markdown syntax in your code comments. You might find that a lot of what you are documenting in the separate .md files could be a notes or remarks section of your method class comments. This will remove the separation of technical documentation vs. help/FAQ comments by doing all of the documentation in the code. You can then add Doxygen to your build, so that building the project refreshes the documentation. Doxygen can be configured to produce a online html version that can be deployed to an internal web server for quick reference. It can also build .pdf, rich text documents, and unix man pages.

Then if you use Continuous integration/deployment, when you deploy to test, UAT, then eventually production you deploy the official documentation that was generated.

The challenge with all documentation, is, Actually doing it. So it should be part of your SDLC documentation and process. the project/task/request is not done until documentation updated. Make it a checklist item that needs to be reviewed in code reviews. Doing the technical and help/FAQ all in code comments makes that easy.

cheers!

* we use Slate for API docs, Google Sites for company documentation (and some Google Docs) * am thinking about using a forum for Q&A e.g. Discourse [2]

Longer:

We've also been going through some thinking on this. At the moment we have an API docs page using Slate, and a Google Sites site which contains a whole raft of documentation. We still have some stuff in Google Docs as well.

Our problem is that not all the team is part of Engineering, so keeping stuff in the repo isn't really ideal (hard to edit). Google Sites is fine but its main selling point is easy access to Google Auth. I have a thread on HN about this [1].

One of the things I have been thinking of is setting up a forum like Discourse [2] for Q&A. Sales often has product-based questions, and vice-versa. In my view, this beats other ways of asking questions (e.g. Slack) because there's no time pressure to answer, and unlike "office-hours" style meetings, it's automatically documented. The only problem is that it is yet another tool.

[1]: https://news.ycombinator.com/item?id=12540678 [2]: https://discourse.org

That's one of the main horrors we are trying to avoid. We'd like to have a single location to track both kinds of documentation ideally, but realise we are probably going to have to make compromises. Tools which keep things in a standard format will ease migration in the future, so something like Slate would be nice and looks a little better than our current way of "Go view the file in Github".

Confluence is a very good wiki. There's no wiki that creates good structures for you automagically.

If someone has "solved" creating a good way to capture tribal knowledge, I'm all ears. But it's not the tools being used that are the issue or the solution.