Should The User Manual Be Agile

While arguing about whether WriteTheUserManualFirstIsWaterfall, we wondered ShouldTheUserManualBeAgile. Are there artifacts generated in a software project (e.g. a UserManual) that should not change rapidly?

There is no technical reason why the UserManual has more 'inertia' than code. While it is being written, the UserManual is kept in electronic form in word processing files. If, as in often the case these days, we are delivering the UserManual as an on-line hypertext document, we may never have to put it on paper and traditional lead time for publishing disappears. In very complex UserManuals, we may have to compile the source text and emit pdf or chm or something. The physical act of changing the UserManual doesn't get much worse than changing the code. If we do have to actually kill some trees at the end, it will still be better to have the final draft written and proofed no later than when the code is finished.

The process of writing UserManuals usually involves workers from an entirely different department with different ideas about how to achieve quality. This is an obstacle that doesn't have technical solutions. How can writing staff be agile? Maybe ProgrammersAreWriters and SpecializationIsForInsects, but corporations will divide labor. There are CFOs, programmers, testers, accountants... all expected to perform different functions. The degree of integration necessary to put the UserManual in the middle of the development stream is still rare. If you could have a dedicated writer assigned to your project they will strongly resist demands to rewrite something as frequently as code changes. Technical writers of this era will view continuous changing of text as a waste of time. Unless and until writers of the manual are also the designers of the resulting software, there is not much benefit to changing the manual before the software.

If the writers are also designing the software, coders benefit because the specifications stay close to the current evolving understanding of the requirements. Clients would get a manual that was more than an inventory of buttons and screens. It would also add context discovered as the product was developed and give them better ideas of how to make their own work more effective with the product. We might generate an artifact that really added value to the product.

We'd have to find people who both wrote and designed. Current corporate cultures tend to specialization and this concept would require generalization.

There is one technical issue: testing. Agile coding relies on tests that let you know, immediately, if your change broke something. Unit testing of documentation is impossible, and there's only so many times you can run an acceptance test (proof reading) before your proof-readers lose concentration.

You can automate simple things, like spelling/grammar errors; and you can potentially check that each acceptance-test scenario has an entry in the table of contents (this assume that each acceptance test is testing something that a user would want to do, and therefore would want to know how to do). But beyond that good documentation is, by its very nature, not susceptible to automation. (Good documentation is more than just a JavaDoc reference manual.)

LineByLineReview provides a case study in these trade-offs. In practice, the UserManual served as a collection of demos, that could be run at any time. Corresponding UnitTests were built to match most demos. The spell-checker complained about correctly spelled words than about misspelled words. The grammar checker did not understand that line breaks can interrupt sentences. The table of contents and page numbering were automatically generated. The authors never considered automated testing of the table of contents.

See UserDocsInXp