This question was raised on a programmer’s group recently and I was intrigued. The programmer’s point was that with many web applications these days there is no print documentation distributed to end users, and even if it existed, many users won’t read it although this makes me wonder who’s buying all those how-to books I see in the bookstore. The programmer suggested that applications should be designed without documentation and wondered about the impact that would have on design.

What Is Documentation?

My definition of documentation is probably a bit broader than that of the programmer.  Print material is the first thing that comes to mind for most people, and PDF documents are merely another format of the same thing. On-line help should also be included in the definition of documentation, and is nearly a requirement these days. Training materials, whether printed or on-line tutorials, should be included as well.

But what about “help text” that is on the screen whether you asked for it or not? Is that user documentation or user interface? It is an artificial barrier to say documentation is distinct and separate from the user interface., for example, has quite a bit of text on the screen at each step of your “shopping experience” telling you what to do now and what you’ll do next. This documentation is an integral part of the design, not merely an add-on item. Unfortunately, on-screen text is too often created by the programmer and does not have the documentation resources behind it to ensure its quality. QA departments try to catch the obvious typos and poor grammar, but, as with most things, it would be better to “do it right the first time” rather than relying on catching and fixing errors later.

From other comments made, it was clear the programmer mentioned above was defining documentation in a far narrow sense than I do, so I’ll stick to dealing with the printed/PDF materials from here out, although to me that is but one component of documentation.

What Does Documentation Teach?

Good user documentation does far more than teach a user how to navigate around a particular application. Useful documentation is often task-oriented and covers not just the “how” but the “when and why you’d want to” of the software. This is true whether or not it is commercial application or a piece of custom software heavily designed around the way a particular company does business.  It ought to describe how the user can do their job (which might cover multiple screens and tools in one section) versus describing in unending monotone the drop-down choices for each field in a screen and telling you to click on the OK button when you’re done.

I think good documentation does get read. The key word in that sentence is “good” of course.  Certainly, there is a huge market for third party books. Independent authors have the advantage of being able to focus on a single category of users and can pick and choose which topics will best serve those users. Many corporate technical writers need to create documents that are all things to all users, as management is loath to invest in enough writers and give them enough time to document their software in any other manner. Dividing material into Administrator Guides and User Guides is about as targeted as most manuals get. Most technical writers are not given the luxury to write for a specific audience.

Impact of Documentation on UI Design

I’ve heard some people excuse a poor design with the comment that “The users can read the manual to figure it out.” Relying on documentation to explain how to use the software is a lazy way to design.  If your company has this attitude, then perhaps eliminating the documentation will lead to improved software design, but you’ll still have dissatisfied customers because of the other benefits that documentation provides.

Design as if There is No Documentation

I do think that software should be designed as if there were no distinct, separate documentation in terms of having the user figure out how to do things they understand need to be done. But, as I mentioned above, useful documentation is task-oriented and covers not just the “how” but the “when and why you’d want to” of software.  Now, if your software is fairly limited in scope and complexity, you could perhaps limit yourself to online help and onscreen text.

Certainly the better the user interface design, the easier it is to explain, which then leads to “less” external documentation. Having documented some really poorly designed applications in the past, my motto has become “If you can’t teach it, it’s not designed well.” I use documentation as a bit of litmus test on the design. Can I explain it readily and clearly? If not, go back to the drawing board (or, these days, back to the Visio diagram).

Users should not have to pull out a manual to figure out how to use the software, but they should have access to documentation to help them learn what to do and when, find shortcuts, read about best practices, and generally learn the bigger picture, and how and where this software fits into their business. If the software allows them to program Web services and your users already know everything there is to know about Web services, they won’t refer to the documentation and shouldn’t have to. A well designed application will allow them to figure out what they need. Of course, if you have the resources to provide good documentation for the advanced user, you’ll be doing even more to ensure a loyal customer.

Document as If the Software Is But One of Many Details

It’s likely that you’ll have a high percentage of users who need to learn not just your software, but about the functions your software is designed to do as well. Again, if the software allows them to program Web services, and they have never programmed a Web service before, they need the details that good documentation can provide. In this case, your documentation needs to explain not just how the software works (“Bring up this dialog and click here.”) but provide guidance as to when to do what. (“Before you begin programming your web service, you’ll need to consider these things…”)

In Conclusion

Good design does not eliminate the need for user documentation any more than good user documentation eliminates the need for a good user interface design. If you have both of these, you’ll have a clear advantage over your competition. The more experienced users will be productive sooner with less effort and the less experienced users will be able to learn enough to be productive for their company, and not just proficient at using your software, both of which lessen the total cost of ownership for your software and make your application more desirable.