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: Think about if 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 would you need to work on “Project X”? This is what your wiki page for Project-X will contain.
I have applied this philosophy to several teams at different companies and it worked. Here is the process that I follow to get 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.