Clients experience me as technology agnostic - but as Microsoft is leading the Web Services pack - I tend to look for projects with a Redmond link. The last few months though my normally Microsoft-centered world has been time-sharing with open-source R&D. Specifically I have been making some cool stuff on the Gentoo distro with Jakarta Struts.

The first thing I did of course was to get a TDD environment in place. That turned out to be much more difficult than it should have been. You know a process needs improvement when you spend hours trying to fix a problem, only to discover it's a 2-second fix that could have been avoided. When the environment was finally ready I was left thinking: how would a developer avoid the pitfalls I experienced? All the grandiose ideas boiled down to one thing: software - especially complex system software - needs to be self-guiding, not simply self-documenting.

John Horch in Practical Guide to Software Quality Management points out...

The best software is not useful if the end user does not know how to use it. User documentation may include not only the user manuals, but also maintenance, operator, training, and other project specific documents, such as the version description document. User documentation provides instructions to the end user of the software system. It addresses proper preparation and presentation of inputs, operating instructions, and directions for the interpretation of the output data. It may also present operating instructions, training needs, descriptions of differences from one version to the next, and maintenance information.

Off the cuff I suggest that software documentation should provide at minimum:

• context-sensitive guidance (task-oriented help);
• predictive, adaptive guidance (user-experience assistance);
• self-patching information (automated documentation updates);
• distributed help content (endpoint mirrors).

Self-documenting is not self-explanatory. If you have ever worked at an ISV then you know the mess challenge of producing high-quality documentation. (I have intentionally avoided distinguishing between types of documentation e.g. design, development, administration, etc. - they share a common goal: software-quality management.) Some of this challenge is ameliorated by development methodology, some by self-documenting code, and some by intuitive tech writers. But without an early and specific commitment to self-guiding documentation, the results are always insufficient to the needs.

Think about your user-experience every time you type: man [software element]. A manual is presented organized to highlight frequently needed information. Usually more information than needed is available, and you can quit whenever you've read enough. Ignoring the limitations of the man system for a moment, what makes it so successful? A standard balance of organization and content, mixed with some context and additional references.

Now let's look at a software that attempts self-documentation, but ultimately fails in user-guidance: GNU Arch (tla). The criticality of properly planning an archive with GNU Arch is well advertised. It is in fact an extremely powerful, but complex product. But somewhere along the way the fact that it is self-documenting was taken to mean it's self-guiding. The newbie - post installation - is dropped off with the following guidance: 1) get a command list via tla help; 2) get specific command help via tla [command] -h. What ensues is a poorly planned archive and/or hours of create/delete trial and error. There is an online tutorial...but it is insufficient, non-distributed content. An improvement in this product's user guidance would be access to best-practices, tutorial content organized by user-story, and examples in the command-help.

You may be reading this, thinking: make good documentation is easy to say, but there's no time to achieve that level of user guidance. If I had time tonight I would list specific studies that show how you spend more time doing call/email-support in the end than if you had good user-guidance in the beginning. I'll leave that for an update later this week. But let's finish on a high note. An example of self-guiding software that works is Gentoo Linux. If you have had the pleasure of installing Gentoo then you know why it works: in addition to the short-list I made earlier, their documentation does not hide details. On the contrary Gentoo is all about exposing all the details, just in a consumable way. Decision points are highlighted and each choice is explained in a pro/con format. Lastly the user can always refer to best practices in case they just don't know what choice to make.

Before I end this piece I would like to suggest the inevitable future of user-guidance, once current software reaches the minimum requirements. Understanding that software development is an extremely challenging effort, and that documenting software is equally mind-bending, why not offload that effort? Distribute user-guidance. There are early examples of this in the Wiki, FAQ web sites we use today. Given a reputation system infrastructure - where endpoints are continuously ranked according to complex algorithms - an ISV should be able to release a product without any documentation. And in short order, a network of distributed guidance should be available.

But that is another post waiting in queue...