Docs that are Part of Larger Systems

It is easy to think of documentation as simply the reader’s companion, which they use when they need help with a product or service. But a lot of documentation is more than this, it is part of an industrial or institutional system. Designing and writing documentation to be part of such a system can be quite different from writing stand-alone documentation.

Software documentation vs. everything else

There often seems to be a divide in the technical writing community between those writing software documentation and everyone else. Everyone else includes fields such as manufacturing, medical, and insurance. People working in the “everyone else” camp often complain that much of what is written about technical communications, and many of its tools and so called “best practices” are only looking at software documentation and ignores the needs and practices of “everyone else”.

Since I come from a software documentation background, I hear these comments in one form or another quite regularly. In particular, when I talk about how users search for answers on Google and arrive randomly at some page in the middle of a documentation set (Every Page is Page One) someone will often remind me that in an industrial setting that is often not the case, that a pilot’s pre-flight checklist, for instance, is not something they find by Googling for “stuff to do before take off”.

Documentation that is used systematically

Such comments are absolutely correct. There is a lot of content that is used systematically. But I don’t think the divide is between software and everything else. It is really a divide between stand-alone documentation and documentation as part of a system. People who use documentation systematically generally do so because it is part of a system.

The pilot’s pre-flight check list, for example, is part of the aircraft safety system. The pilot does not stumble upon it when another pilot tweets a link to “Cool checklist. Really useful before #takeoff. bit.ly/flysafe”. They are trained to use it. They are trained to know where to find it. They are trained to understand exactly how to do each check on the check list. As such, they learn nothing new from the checklist. It serves as a reminder, and as a means of validation and verification that the pre-flight process has been done completely and correctly.

The Toyota production system stresses continual innovation and improvement in every aspect of the production process. They also prominently post detailed work instructions that spell out every detail of how each job is done. That might seem like it would stifle innovation, but the real reason for the detailed documentation of the work process is not to ban innovation, but to provide a baseline against which innovation can be measured. It often functions more to inform the supervisors who are looking for ways to improve the process, rather than workers who are doing the work on the shop floor. Again, its function is not to teach, but to measure. As such it is part of an industrial quality improvement system.

Documentation written to stand alone

By contrast, much of the documentation that is written in the software world, and, of course, in the consumer products world, is written to stand alone. The operating assumptions is that the user will acquire a  product or service and will use it without requiring any qualification, supervision, or training. They will turn to the documentation at a time of their own choosing, for their own purposes. There is no larger system: it is just the user, the product, and the docs.

This, certainly, is the scenario that John Carroll constructed for his experiments that led to the theory of minimalism: people alone in front of a computer with a pile of documentation beside them. It is also the environment that is constructed in most usability labs today.

One of Carroll’s key findings was that people have great difficulty using documentation that is written to be read and used systematically. He called it the paradox of sense-making. When people’s existing mental model of a task does not match the model of the product they are using, they don’t trust or understand what the systematic instructions are telling them. Thus, as I argued last week, the reader’s path cannot be made straight. They need to learn by experimentation, failure, and error recovery.

The prepared reader

But while that is true for stand-alone documentation, where the reader’s level of preparation cannot be known, it isn’t the case where documentation is part of a system, for one of the things that any good industrial or safety system will ensure is that people are properly prepared for each role they play in the system.

Software and the unprepared reader

If the divide between stand alone documentation and documentation as part of a system seems to follow the divide between software and everything else, it is perhaps due to the fact that, in itself, software is safe to play with. You are not going to hurt yourself or others playing about in a word processor or a spreadsheet or trying things out in a programming language or a CMS. Bits don’t sting, so you can play with them without danger. Thus you don’t need systems to prevent people using software from hurting themselves or others. You can thus afford to issue stand-alone documentation and let them figure it out for themselves. This, in turn, greatly reduces the cost of software products, which greatly increases their market.

Software and systematic documentation

Of course, software is often used to control machinery, and to direct financial systems whose incorrect behavior can have devastating consequences. In fact, software control is now so ubiquitous that to suggest that there is a substantial body of documentation being written that is outside the software space really doesn’t hold a lot of water. It is all software documentation — the real dividing line is whether the software is running a system that can hurt you.

Once we get to the point of writing control logic for dangerous machines and systems, the need for safety systems and for careful qualification and supervision of people and systems kicks in. At that point, we enter the world of documentation as an element of a system.

One thing we should never find in such a system is a reader who is unprepared for the documentation they are reading. The paradox of sense making should never apply here. If it does, the system is broken. Features of the minimalist approach, such as omitting details and providing hints rather than explicit procedures do not apply. The purpose of the documentation is not to encourage exploration but to ensure correct operation and safety.

Training people for the system

Of course, any such systems requires a method for training and qualifying workers before they are allowed to work with the system. When they start their training, they may well have a mental model that does not fit the system they are being trained in, and so they will experience the paradox of sense making. If minimalist documentation interferes less than systematic documentation with learning, it may be appropriate.

However, minimalism’s approach to helping users make sense of things is to encourage experimentation and support error recognition and recovery. It can only really be used in a safe environment, where experimentation and error can be done safely and at a manageable cost. This is, of course, why many industrial processes use simulators for training purposes — to provide a safe place to experiment and learn. In cases where simulation is impossible, long periods of apprenticeship and supervision are common, to expose the new worker to the dangerous environment in a safe way, so that they can learn from experience without killing themselves and breaking things. Once again, therefore, the documentation used in training for such environments is part of a carefully constructed and controlled system.

EPPO in systematic documentation

Where does Every Page is Page One fit in the world of documentation as part of a system? Certainly, one of the major arguments for Every Page is Page One — the reader dropping into the content at random from a Google search — does not apply in such cases. However, findability of content is still a major concern in such environments, especially in complex environments where there is a lot of documentation required, and we should not fall victim to a historical myopia that supposes that the systematic organization of content must necessarily be linear or hierarchical.

Even workers who have been thoroughly trained to understand content when they find it, may still struggle to find content, particularly if it is content they rarely consult — which can often be the content they need in an emergency, particularly an emergency that is not unfolding the way the drills said it would. In such cases, the ability to access content in other than the designed sequence can become critical to life and limb.

On such occasions, the ability to swiftly identify the piece of content you need, to quickly get to the right piece of content if you are in the wrong place, and to quickly find the supporting information you need on a particular point, are just as important as they are when docs stand alone. The key characteristics of Every Page is Page One topics, therefore, apply just as much in documentation that is part of a system as they do in stand-alone documentation.

This is how those characteristics support documentation that is part of a system:

• Being self-contained — providing exactly what is needed at this point in the system
• Having a specific and limited purpose — focusing on what needs to be done now
• Establishing context — making sure the reader knows exactly where they are
• Following a well-defined type — ensuring they are complete, clear, and easy to follow
• Staying on one level — not deviating from their role in the system
• Assuming the reader is qualified — because that is what the system is designed to ensure
• Linking richly to ancillary material — to make ancillary and supporting material readily available.