The “THUD” is outdated IMHO, and whilst I may be lucky that we don’t print our manuals, we still have a 900-odd page beast of a Developer’s Guide to maintain. We’ve yet to tackle cutting that down as, because we work in an Agile environment, we struggle to find time to do the ‘non-writing’ tasks.

But we do try and document everything. Rather than making a cut of “do or don’t” we try and make it “lots or little”, and whilst we occasional get the balance wrong, I’d much rather a user complained that the documentation was missing information rather than just “missing”!!

One downside to Agile is the entire focus on the software, testing is usually included (or should be) as part of test-driven development, but as yet I’ve not heard much mention of documentation-driven development… other than a blog post or two.

That said we are currently re-positioning the writers further up the information stream. Currently they sit with the development team, and document ‘stuff’ as it is built (with a lag of a day or two). In the future we will write the user stories that the developers will then break down into tasks. In other words, we will write up the conceptual topics FIRST, before any other work starts.

That should allow us to get a good handle on the amount of documentation required for a given concept. However it does presume you have the correct ratio of writers vs developers, and yes, it is higher than you think!

Gordons last blog post..UA Conference

avis last blog post..המטבח האובייקטיביסטי * האולטימטיבי

True, online help allows you to document everything without the accompanying heart-sinking “thud” of a huge printed manual. But for us the issue is always: what are we going to document given our extremely limited resources?

For us, not only do most users never read the printed manuals, but most of our users never even clap eyes on a printed manual. So, although we are under fairly constant pressure to produce printed manuals (because of management expectations that there ought to be a stack of printed manuals because there always have been in the past), we try to keep uppermost in our minds: what are the users going to find most useful. And, much of the time, we have to narrow this down further to: what do users really NEED.

The great thing about doing documentation within an Agile team is just the fact of being embedded within that team and documenting alongside the developers with the aim of producing great documentation for each release. Prior to working in this way, we often did documentation retrospectively, so the docs sometimes lagged a release (or two) behind the software.