In The Tyranny of the Terrible Troika, I complained that the now almost universal trio of concept, task, and reference did not properly represent what topic-based writing and information typing are really about, and I promised to show why each one, as popularly practiced, fails as both a topic type and as an information type. I begin with this: a task is not a procedure.
The most commonly used “task topic” type today is that implemented by DITA, in which a task topic is essentially a procedure. A procedure is certainly, in the Information Mapping sense, an information block. It is a distinct literary form, with a defined set of rules and a clear beginning and end. You can certainly create and structure procedures as discrete blocks of content. But they are not task topics.
The distinction should be very clear. A task is something a user has to do, a goal they want to attain. A procedure is a set of instructions for manipulating a machine. Manipulating the machine is never the user’s goal in itself. Manipulating the machine may be one of the things the user has to do to accomplish their task, but it is not the task itself. A procedure, therefore, may be part of a task topic, but it is not a task topic in itself. (I am using the word “topic” here in the sense I defined in What is a Topic? What Does Standalone Mean?)
In many cases, however, accomplishing a task does not involve manipulating a machine — or at least, not manipulating a machine in a way that is specific to the task. A great deal of the technical documentation I have written over the years has been for programmers, where the product was a programming language, an API, or an operating system. People doing programming tasks use the same tools they use all day every day: editors, debuggers, compilers, etc. No one programming task makes any special use of these tools.
Creating rules to process an XML content stream and writing code to control shared access to a serial port are both programming tasks. They both use editors, debuggers, and compilers — but not in any way different from how these tools are used in every other programming task. Programmers do not need or want to be told how to type a function or set a breakpoint in every single programming topic in the doc set. Programming task topics, therefore, generally contain no procedures at all.
Most programming task topics are built around code samples, not procedures. Indeed, if you were defining a structured task topic type for a programming task, you would almost certainly make at least one code sample mandatory. But you would not make a procedure mandatory. Procedures are simply not relevant information blocks in a typical programming task topic.
Another common task type when you are writing about programming, and about operating systems in particular, is a configuration task. Getting the system configuration correct is vital to any OS-based project, but unless you have a GUI configuration tool, there are not usually any special machine manipulations involved. Configuration is generally done by writing a text file. It might be an XML file, or a file containing a series of configuration commands. In either case, the task of configuring a system has nothing procedural about it. In fact, it is almost all about planning.
Configuring an operating system correctly for a particular device is all about making the right set of trade-offs between functionality, size, speed, and security. A configuration task topic for any sub-component of a system is mostly a checklist of things to think about: how many communication channels will be required for different applications to talk to each other. How much memory will each application need? How much stack space? Just as a code sample is central to a programming task topic, a checklist is central to a configuration task topic. Procedures play little or no role in either one.
There can be much more to it than simply building a topic type around a code sample or a checklist rather than a procedure. Every operating system has an API. Programs written to run on that operating system call that API to interact with all the peripherals and components of the system. On a desktop computer, the entire operating system is generally installed by default (with perhaps some obscure exceptions), so the entire API is available to all programs. But on an embedded device such as a digital camera, a microwave oven, or the guidance system of an ICBM, the operating system is configured to include only those parts of the API that are necessary for the code running on the device. Embedded operating systems are packaged in thousands of separate modules, and the OS configuration that is actually loaded on any particular model of a device is probably completely unique to that device.
Add to this that the device software on may devices is required to work in real time. That is, not only must the automatic pilot be capable of figuring out how to fly the plane around the mountain, it must be guaranteed to figure it out and execute the maneuver before the plane hits the mountain. Not only this, before the plane is allowed to fly with this software, the manufacture has to be able to prove, to a very strict standard, that the auto pilot software is capable of doing this.
This means that there are a great many things that a programmer of avionics software needs to think about that a regular programmer does not. Every programming task for an avionics programmer is complicated by considerations such as:
- Is this function supported by the version of the OS approved for this device? (Approving a new OS module might cost a million dollars or more!)
- Is this programming technique deterministic (meaning it will always function in the same elapsed time each time it is run)?
- Will this programming technique cause my code to run in a way that compromises the deterministic nature of other threads in the system?
These are really important questions, and if you are writing a programming task topic for a real-time embedded systems programmer, you need to make sure you treat these kinds of subjects in every programming topic you write. This is what information typing is, or should be, about. It is, or should be, about making sure that every topic of a particular type does the whole job it is supposed to do.
When people are making the case for technical communications, they often point to technical communication problems that contributed to notable accidents. This kind of information typing is a vital part of what you do to avoid those kinds of issues. Providing a mechanism for breaking content into chunks and reusing the chunks may save a company money on its technical communications budget, but it does little or nothing to prevent the errors and omissions that lead to user frustration (at least) and the catastrophic loss of life and money (at worst).
In What is a Topic, What Does Standalone Mean?, I made the distinction between what it means for a piece of information to exist separately (as a procedure block might), and to functioning separately (as a complete embedded systems program or configuration topic might). The standard, in other words is not reusability, but usability.
This is what topic-based writing and task topic types should be about, therefore: creating topics that function for the user by consistently and reliably enabling them to accomplish the whole of their real-world tasks. This is about a great deal more than procedures, and there is a great deal more at stake than reuse.
Reuse is an important goal, to be sure, and money saved by reuse can help improve docs in important ways, but reuse, both in its implementation, and in the content models that support it, must be a subordinate goal and a subordinate function to the real function of information typing, which is designed to enhance usability and reliability.
And real information typing, the kind that produces strongly typed topics that are guaranteed to do the job they were designed to do, can save you money in other ways, by increasing the opportunities for automation and reducing the content management overhead that can slowly cripple loosely-typed systems.
Structuring and writing a task topic for a particular domain, such as avionics system programming, is about much more than chunking procedures separately from the rest of your text. A task topic is not a procedure.
Image Copyright (c) 123RF Stock Photos.