Personal vs. collaborative documentation

Yesterday, we discussed the importance of a personal note-taking tool. We can also extend this concept to a team or company using Wikis, Markdown in Git, shared Google Docs, etc.

Collaborative documentation is very valuable -- IF you can get group participation. Over the years at various companies, I've set up Wikis as collaborative documentation efforts. Most of them resulted in only me contributing. Group initiatives like this need to come from the top, otherwise there is very little incentive for people to contribute. As a result, I've pretty much given up on Wikis for small teams/companies -- it is nearly impossible to get momentum and maintain the information. This is sad because so much knowledge is lost and effort wasted as the same things are rehashed, relearned, and re-communicated.

As a result, I now focus primarily on:

• My own personal notes system
• Markdown in project Git repos

If I'm going to be the only one creating and reading notes, it may as well be in my own personal notes system which is most convenient for me.

For project documentation, this is best maintained in the Git repo as close as possible to the source code or design files. There it has a better chance of documentation being maintained if it is worked into the PR workflow and review process.

In the course of product development, documentation is the hardest deliverable to produce because its effects are hard to measure. Initially, the product still functions without documentation. Documentation costs short-term but produces compounding gains long-term. It is an investment in the future. If your team or organization is not interested in making this investment, you can always make it personally.