Every dev team knows that they should have more documentation than they currently have. However, writing docs is no-fun. I have written a few blog posts about this sad topic. It is hard for developers. Because, not only is documentation no-fun, it also subtracts from your productive (ie, programming) time. It also creates a little bit of debt, because it is one-more-thing that you need to maintain regularly. If you don’t, then the docs gradually lose their value.
So, to maximize ROI, I usually start a team with the simplest, most 101 kind of documentation: a dev wiki.
Here is the concept: Imagine that you are a new developer or temporary contractor (for only one day). Everyone is gone, but they gave you permissions to everything you would need. Now, what kind of instructions will you need so you can understand and work-on “Project X”? This is what your wiki page for Project-X needs contain.
Process: I’ve been successful at applying this process/philosophy for several teams at different companies. Here is how you establish momentum:
- Start with this reasonable concept, like the example described above (up 2 paragraphs). Keep it simple and quick.
- From the answer, create a template (which is always much easier for a developer to fill-out, instead of just a blank page).
- Identify all of the projects that your team maintains. Create stubs (copies of the template) for each.
- Each developer gets project(s) assigned to them. He/she will fill-out the doc template for each and then will be responsible to maintain those docs.
- Each month, as part of each person’s monthly status report, each developer reports which projects were updated in the wiki.
- Monthly, I spot-check 10% of the wiki articles to see if any were out-of-date. If so, the responsible developer gets a reminder about our team’s commitment to this documentation and it is “for real”
Do NOT get carried away. These need to remain very simple, with minimal words, to provide a high value with low maintenance.
The wiki was a simple starting-point that made a big difference for our team. It wound-up being a solid proof-of-concept that inspired other IT teams. They adapted our templates to fit their team’s needs.