Tom Opgenorth opines and asks about technical documentation on the ALT.NET list:
...on this contract I'm leaving, there really isn't a lot of
staff, nor is there a lot of format familiarity with some of the
design patterns (hence my desire to leave behind some sort of formal
document). Mostly I'm thinking of stuff like
* Architecture (very broad, I know).
* Database schema/changes to existing schema
* Layout of projects, and the dependency of assemblies
* explanation of tricky algorithms
* hardware specs (they have some custom hardware it's own specs)
A lot of this stuff as fitting into the XP notion of a coding standard (which should include project layout). A good TDD practice will also surface "excutable specifications" or you might be using FIT to leave a breadcrumb trail of documentation. Still, some documentation is usually a good thing, especially in a consulting hand-off scenario.
Tom's bullet points are a lot like tags or categories in a blog. I think a lot of these items could easily be captured as blog posts, etc. This content will likely get tweaked over time, so a Wiki is a better fit conceptually (I don't usually go back and modify blog posts). I'd maintain that the chronological view of the blog meshes well with the re-entrant, evolutionary, and collaborative nature of a Wiki.
We maintain a Wiki for our technical documentation. Just now, I asked one of our developers to write a stub article about some faxing feature that we have. Essentially a Wiki is a lot like a communal blog and is an excellent tool for evolving a set of documentation around a product. We've defined separate Wikis for:
- Practices & Tools (Links, Pointers, Coding Standard, Software License Keys)
- Company (Housekeeping, HR)
- One-per-product
What we can't capture in a self-documenting style or executable spec form we can usually capture in a small-to-medium blog-style article. The key, as with any good piece of writing, is to strike while the iron's hot (write when you think about it, you can improve it later) and keep the scope of your article focused on one aspect of your system. Small-to-medium is important as well; content can grow and be pruned over time as necessary.
Tom's outline is a good place to start thinking about the "categories" for these articles, but I'll add a few more:
- Model Distillation Documents (ala DDD)
- Technical Debt Exposés
- Experience Reports, Spike Outcomes, Product Evals
- Interview Transcripts, Ethnographic Studies
- System Philosophies, Assumptions, Metaphors, Inspirations
- Manual Test Plans
Of course with a folksonomy you can tag and let the popular tags emerge. The tag cloud becomes a useful visualization for segregating the content you're interested in at any one time. In any event, I'd recommend a Wiki-per-product and a Wiki-per-team; keeping them small, portable, and focused helps set a tone for what does and does not belong in documentation. When you're about to close that story you've been working on, stop for a moment and ask yourself, "should I write an article or two (even if it's a stub)?" A micro-investment in the present will help reduce documentation debt which can be a hard thing to overcome.