Agile Documentation and Manuals - Testing

Should The User Manual Be Agile:



'via Blog this'



I have spent far too much time writing and maintaining manuals (for computer architecture) in the last year.



Since I have drunk the koolaid of Agile Development in software (test driven design, refactoring, pair programing) and have tried to evangelize Agile Methodologies for hardware development and computer architecture (with limited success - e.g. Intel has adopted something like scrum, although I hesitate to call it agile), I naturally think about how to design Agile principles to writing and maintaining technical documentation, computer architecture manuals, etc.



Of course, Ward's wiki has some pages on this: Should The User Manual Be Agile. WriteTheUserManualFirstIsWaterfall, ManualAsSpecification, WriteTheUserManualAsYouGo...  Of course, Ward's wiki is very stale. I recall discussions on agile mailing lists such as the [XP] mailing list.

But quick googling does not find much in the detail that I am thinking about.



A big frustration in my current work is that I had more automation in the documentation and manusl in my undergraduate RAMM/RISC/SEISM computer project in 1985 than I do now. I generated much of the manuals from high level descriptions of instruction encodings, and so on - in fact, I actually generated the instruction encodings.



However, over time I encountered much resistance to tools that generate correct documentation. So in some ways I have switched to emphasizing tools that can VERIFY that handwritten documentation is correct. Although I am still happy to generate whatever can be generated.



Of course, either of these approaches - generate or verify, automatically - requires the ability to automate. It is easy to automate text based markup - nroff, LaTeX, XML, SGML. Wiki markup. It is harder to automate when you are dealing with obsolete versions of binary formats like FrameMaker's binary .fm files.  (MIF helps, but is limited.)  Semantic markup helps a lot, as do wirdprocessing macros with meaningful names.



As many of the references point out, testing manuals and other documentation can be challenging.  There is simple stuff - spell checking, automatically checking table of contents.   Literate Programming techniques can be fruitful.  I believe the Itanium manuals defined instruction semantics in terms of pseudocode that could be extracted and run in a simulator.



But there are other steps.