Posts Tagged YAGNI

Documentation is often an afterthought in software intensive projects. Adding documentation after the fact is no fun, but an important part of software creation nonetheless.

In an agile project, there is no “after the fact”: you’re forced to create and update documentation in the same task, or at least the same iteration, as you create functionality, or there will be no documentation at all. You don’t have “documentation sprints”, do you?

How do we do it?

Put simply, in my current project we try to document everything that does not fit the “it” in YAGNI.

• We have a set of long-lasting base documentation: an architecture overview that fits on about 10 printed pages (including a discussion of the goals of the product), and some high-level designs, mostly describing how to map the customer’s domain to our architecture.
• Requirements are documented as rough user stories, accompanied by user interface designs created by our experience designer.
• Our code contains quite some documentation: of course on how to use the code, but also on the exact interpretation of certain requirements. Automated tests (from unit tests up to UI tests and system tests) are codifications of requirements, and useful as documentation in their own right. I’ll put up another post about how to handle documentation in code someday.
• The user manual is handled by a professional technical writer. He’s usually one sprint behind, catching up with the features that get created or updated. His main input is the requirements documentation mentioned before.
• The development trail consists of the Jira issues we work on, updated with work logs, comments, and links to related issues or parts of the documentation.

All pieces of documentation should have a URL of some kind, so we can easily link them together: we use Jira as an issue tracker, and Confluence for documentation. Due to internal reasons, we fell back to MediaWiki for documentation; while this is not as good for ‘living’ documents as Confluence is, it sure beats SVN-controlled Word documents.

How does that work out?

Over the past year, we’ve hardly touched the architecture document, except for one major overhaul when there was a second product to be built from the same codebase. The high-level design documentation does get updated, usually by adding sections on mechanisms that are hard to describe in code and comments alone.

The user requirements documentation is about as lively as the codebase itself: it has been used as a basis for customer discussions, and has lived on as a reference manual for “what should this feature do exactly”.