I’d Rather Be Writing - Tom Johnson

Thanks for the thoughtful post, Tom. I’ve had a similar reaction to yours.

You quoted Fowler: “If you document everything, you are giving everything an equal weight.” - Uhm, no. I’d say you didn’t structure your documentation well. If you give everything an equal weight, you’ve written encyclopedic reference documentation, but neither instructive conceptual documentation nor guiding procedural documentation. While reference documentation allows (or requires) equal weighting, it’s unsuitable to teach concepts, tasks or procedures. (See Thomas Barker’s _Writing Software Documentation_ about the three types of documentation, http://www.writingsoftwaredocumentation.com/).

It may be a strategic decision in agile development to favor one type or omit another - but you should be aware of the cost of being complete or instructive or both.

Along these lines, I think that “fear of the thud” is really asking our users to judge the book by its proverbial cover. I don’t care how thuddy the documentation is as long as I can use it quickly and comfortably. Give me clear and quick access to relevant task documentation in the front, and I’ll confidently use the reference documentation in the back - even if the whole thing clocks more pages than Tolstoy.

I also object to adapting scope and process of the documentation to the development process as opposed to user requirements. I’m documenting a commercial software system that’s highly complex, but also developed on a tight schedule. I can’t see that users would be glad to go without comprehensive help because it didn’t suit our development timeline.

Tom:

As a Scrum Practitioner and a writer, I advocate writing along strict minimalism lines. In the talk circuit I’ve been on lately this has had mixed reactions from the writing community.

The biggest advantages to Scrum occur when you bring customers in early in the process to review what you are doing. They can then help set the priority of what they will be using the product for and guide you to areas where the doc needs to be ‘bullet proof’.

In most other cases, I advocate the 80/20 rule with the acceptance that customers will complain but Scrum allows me to quickly and easily address their complaints/concerns.

In an Agile/Scrum environment you don’t have time to fill out the edge cases. You’ll need to accept the fact that the edge cases will come to you and that you can fix them when they occur.

Its a hard pill to swallow but its also the key to survival working with light-speed development.

@Kai, I appreciate your comment on this post as well as on others. Also, thanks for the link to the Writing Software Documentation book. I’ll have to check it out. Actually, that gives me an idea for another post.

Re structuring your document to give it emphasis, I agree, but this of course takes skill. Usually we organize like topics in the same sections, right? So if you have one section with 10 topics, only 2 of which are essential, where do you put the other 8? In a reference section at the back?

@ Mike, working at light-speed development seems interesting. I work in an agile environment, but the iterations are only every 2 months or so. I suppose it’s a modified agile methodology.

One thing I’m curious about. With frequent releases, does QA testing get cut short? How do you ensure you get all the bugs out? Or is buggy software part of an agile development? It seems like the frequent release cycle requires QA to dedicate more effort than lengthier iterations. (I know that has nothing to do with writing.)

One thing that has been invaluable working in an agile environment is to be embedded in project teams. Because changes occur so rapidly, without formal requirements docs, writers need to be there when the informal conversations go down, so to speak. It doesn’t work if you’re sitting in another department or area.

I really enjoyed all the comments on this post. You guys enrich and deepen my understanding all the time. This is another argument to keep writing, even if I’m not an expert on the topics I’m approaching.

@Kai: “One solution is to prominently offer users different paths through the documentation…”

It is a solution; but whether desirable is another matter.

In short, pathways ask the user to 1. stop what they’re doing, 2. perform a task analysis on a task they don’t perfectly understand, then 3. select a path through a document that may or may not describe their needs in toto. Such an approach seems intimidating.

@ Tom: Our documentation follows minimalist design patterns. Primarily we document what we perceive as pain-points for the user. Inline support is preferred, but where a longer article is needed we try to keep it to ~250 words max. Both of these are informed by our team’s involvement in designing the interface (we are very pleased when no documentation need occur).

Lots of interesting thoughts here. I’m glad our podcast help to kick off such a good discussion.

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.

I’ve been pondering this for a while, since hearing the podcast as well.

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

[...] How Much Should You Document? Everything? Strategies for an Agile Environment [...]

@ Alistair, Thanks for the comment. I really enjoy listening to your podcasts — I hope you maintain your current pace. I can see how limited resources would force the question of what to document. I’m also in an agile environment, albeit a bit slower one. I ensure the main features are documented at the time of release, but since I publish the help independently of the application code, I can always go back later and add more details. I often add the video tutorials after the release because there’s just not time to create them the week before, especially when the UI is still in flux.