Soft Documentation

As a software user I expect software to just work—especially software with a GUI. It should be obvious what to do without needing to read the manual; and preferably without even waiting for tooltips to float into view. By designing a GUI which operates within a web browser we already have a headstart here: the user interface is driven like any other web interface—there's no need to document how hyperlinks work or what the browser's address bar does.

What's more, the Manifesto for Agile Software Development explicitly prefers: "Working software over comprehensive documentation".

These considerations don't mean that the manual is redundant or unwanted, though. There are times when we don't want to clutter the core user interface with reference details. There remain occasions when hardcopy is invaluable.

What's more, when you try and design an intuitive user interface, you realise that the distinction between software and documentation is somewhat artificial: it's not so much that the boundaries blur as that, from a user's point of view, they aren't really there. Suppose, for example, that a form requires an email address to be entered. If the user enters an invalid address the form is redrawn with the erroneous input highlighted and a terse message displayed: Please enter a valid email address; there will also be a clickable Help icon directing confused users to the right page of the user manual. Which of these elements of the user interface are software and which are documentation?

Now suppose we are delivering a library designed to be linked into a larger program. The documentation is primarily the header files which define the interface to this library. We must invest considerable effort making sure these header files define a coherent and comprehensible interface: maybe we deliver the library with some example client code and makefiles; maybe we provide a test harness; maybe we generate hyperlinked documentation directly from the source files; and maybe we supply the library implementation as source code. Now which is software and which is documentation?

When we write software, we remember Abelson and Sussman's advice:

Programs should be written for people to read, and only incidentally for machines to execute.

In other words, software is documentation. Software should also be soft—soft enough to adapt to changing requirements. We must be sure to keep our documentation soft too.

Copyright © 2006 Thomas Guest