Disclaimer

The content of this blog is my personal opinion only. Although I am an employee - currently of Nvidia, in the past of other companies such as Iagination Technologies, MIPS, Intellectual Ventures, Intel, AMD, Motorola, and Gould - I reveal this only so that the reader may account for any possible bias I may have towards my employer's products. The statements I make here in no way represent my employer's position, nor am I authorized to speak on behalf of my employer. In fact, this posting may not even represent my personal opinion, since occasionally I play devil's advocate.

See http://docs.google.com/View?id=dcxddbtr_23cg5thdfj for photo credits.

Wednesday, September 17, 2014

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. WriteTheUserManualFirstIsWaterfallManualAsSpecificationWriteTheUserManualAsYouGo...  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.




2 comments:

Andy "Krazy" Glew said...

One of the most basic tools in AgileDocumentation must be diffing - document comparison. FrameMaker's compare documents utilities helps, but has much missing - e.g. the version I am using almost always gives up on tables. DiffPDF helps, but has problems.

Diffing not just because it allows you to compare document versions. But also because it allows you to do simultaneous edits of the same file, encouraging ContinuousIntegration.

Andy "Krazy" Glew said...

Diffing is also the basic element of manual testing: seeing what parts have changed. Verifying that the changes are correct.

Of course, diffing only allows you to see the changes that have been made. It does not allow you to see the changes that have not been made.