Documentation and the Case for Better Navigation

online_vendor_documentation

Some of these ideas are from Mark Baker’s blog, Every Page is Page One.

The first challenge of documentation is to get the user to use the product. It doesn’t matter how usable it is if it is so off-putting in appearance that no one tries to use it.

Some of the things we document are complicated, but it doesn’t mean that every individual task, feature, or concept needs to be complicated. Throwing all the content in the user’s face when they look for help with something simple is distracting. It only serves to discourage users from trying and learning.

Take the classic tri-pane help system. It may be full of utility–multiple ways to view and navigate the content, multiple buttons to push to move around it in different ways. But, it screams “Look how big and complicated I am. Look at how many pages there are. Look at how deep they are nested. Look at all these controls you will have to use to navigate me!”

A PDF is far less usable than a well-organized online help system, but it is actually clearer. It presents a single pane and a search box, and everyone knows how to use a PDF. Videos are even better, but they are lousy for many tech comm tasks — tedious, impossible to navigate, impossible to search, impossible to use for reference— but their entire interface is a single triangular button. No wonder users ask for PDFs and videos even when they are not appropriate or usable. They just look so much better.

With the web, the user is not restricted to a TOC or index — you can offer relevant links on every page that allow them to move effectively through the content without ever being aware of how extensive it is or how complex the product is. If they want to explore any of the topics, they can do so simply by clicking a link. Each topic is a navigation hub.

Adopting this view of organization is important because as our content becomes larger and more dynamic, it becomes more and more difficult to navigate using a fixed table of contents. Seeing everything at once is too overwhelming or general, and artificially segmenting it is too confining.

With the web model, you can create documentation that looks simple while remaining thorough and comprehensive in the depth of its coverage. This way, you can have a large information set with manageable navigation at every point, but still have the ability to travel very far across it.

 

Does Topic-Based Authoring Help Readers As Much As It Does Writers?

topics2

*Due to web issues, we lost information on who authored this piece.  If this is your work, please let us know and we will give you publishing credit.*

Many large companies have adopted a modular, topic-based approach to technical documentation. This is mainly because content can be reused in various ways from a single source, preventing multiple versions of the same information. This approach helps writers publish the same information in different combinations to different media (for example, mobile devices and TV screens).

Does topic-based authoring also help readers? In a number of ways, it does.

Structured content helps readers because the format and approach are consistent, therefore it is easier to use and understand, even when it is accessed from an index or search.

Standalone topics are based on their content type: tasks, concepts, and references. For example, tasks provide the steps necessary to perform a specific goal; concepts provide a way to understand how that goal fits into a larger scheme of information; and references often provide alphabetical lists in tables, such as a command options list.

Separating descriptive information from task-oriented information helps readers access only what’s relevant to them. Topics provide just enough detail for readers to understand the content contained in each one without having to look somewhere else.

Linking related topics is an important part of modular documentation. Links help readers navigate, and the information they find will be exactly the type of information they need. If different topics are written by different authors, readers should still be able to navigate efficiently through the content to find what they’re looking for. For example, task topics almost always have related concept topics, reference topics are referred to by multiple concept topics.

Mark Baker, who writes about developing task-oriented, topic-based content in his blog Every Page Is Page One, points out that “breaking down content into small structured units is a good way to improve consistency and productivity.” Topics help readers, he says, when they include context and links. “Context can be a sentence or two that helps readers figure out what the topic is about and how it relates to other topics, for example, what it covers, what release it applies to, and what type of information it is (task, concept, or reference).”

So perhaps the answer is that what helps writers also helps readers.

Have something to add? Please share it in the comments.