August 16, 2010

A Tale of Two Doc Types

As I see it, modern technical documentation comes in two basic formats: books and help systems. The key differentiator is the reader's expectation about how the documentation is used and not the actual production medium.
Books are intended to be used in a linear, narrative fasion. A user expects to start at one point (a chapter head or section head) and then move forward through the pages to gain more detailed information about the task identified on the start page. A chapter starts off with an overview of ESB processes and then proceeds to provide more granualar information about them. Location has meaning and the content flows together to build a complete picture.
Help systems are intended to be used contextually like a web. A user expects to be dropped into the system at a topic that is relative to the task at hand and then traverse links to any relative information. The idea of chapter and section are meaningless. Location is valueless and each page is a relative island with bridges leading to other islands that may provide further information.
In PDF, and print, the difference between a book and a help system is hard to define except that the help system will almost always feel incomplete and disjointed. PDF, like print, is meant for linear content since it is harder to jump around and the viewers all prominently display location.
In HTML, things are more flexible. HTML books can feel linear and help systems can feel web-like.
HTML books should prominently display their TOC and provide some indication of position in the TOC. They should also provide navigation buttons for traversing the content linearly. Clues like the word chapter and section also help orient the user.
HTML help systems, while most have a TOC system, can dispense with a majority of the location trappings since location has little value. Help systems should not have linear navigation tools, since linear navigation does not always translate into the expected behavior for the user. Words like chapter and section should be expunged since they confuse the user by implying organizational constraints that are not valid in the help system.
Things get confusing for help systems since they often have a TOC panel that displays a linear organization of pages that appear to be grouped into nested structures like chapters and sections. Look at an Eclipse help system's TOC and it is easy to think that it can be used like a book. Start using it that way and you will soon become frustrated because, even if there was a way to navigate linearly, the actual content is not linear in the same sense as a book. Some high-level topic may be a big process that the nested topics provide detailed sub-processes and context, but it is rarely the case that it flows like a book. It is intended so that a user can quickly land on a single page, perhaps by triggering F1 from the UI, and get the information they need. They can choose to explore the provided links to other topics or not. In a book, they would likely need to click through to the pages that follow for more information.
A book is a longer, more descriptive, leisurely way to learn about something. It is intended as a way to deliver content at a deep level in a pedigogical manner. A help system is a collection of quick cards that deliver targeted information so a user can get on with the task at hand. The idea that a writer can create a document that fits both purposes is foolish. The result, like all attempts at making hybrids, will be something that does neither job well.

No comments:

Post a Comment