Designing topic types

A number of readers have asked me to write about how to design a topic type. Although it can sound complicated, especially if your bring XML schema definitions into the mix, designing a topic type is actually pretty simple.

Before we begin, though, set aside all the issues around XML. XML has nothing to do with topic type design. It may have a lot to do with how you implement your topic types (or nothing to do with it), but it has nothing to do with how you design them.

Needed information in a specific form

A topic type is essentially two things:

• A list of the pieces of information a reader needs to accomplish a particular purpose.
• A standard form and order for presenting that information.

That second property is important. Typed content has a specific format. Typed content looks different from untyped content. Thus the well known topic type of a recipe makes it immediately obvious that a certain piece of content is a recipe.

The thing that makes the recipe type distinct and obvious is the list of information it contains and the particular form in which that information is presented. The basic recipe topic type is:

• A list of the pieces of information a reader needs to cook a particular dish: At minimum, a description of the dish, a list of ingredients, and a set of preparation steps.
• A standard form for presenting this information, in particular a standard form for presenting a list of ingredients, consisting of a table or list with the ingredient name on the left, and the quantity and unit of measure on the right.

Similarly, the well known topic type design for an API reference entry is:

• A list of the pieces of information a reader needs to use an API function: the name of the function, the function signature, a list of parameters and their meaning and type, the return type of the function, and a description of its use, with examples.
• A standard form for presenting this information, including the order in which the elements are presented, and the standard way of showing a function signature and a parameter description.

Needed information depends on the business context

In many cases, the list of information that a reader needs to accomplish a particular purpose is specific to the business context or the technology they are using. For example, I once worked on documenting the configuration of an embedded operating system where there was a vital business need to trace the dependencies of every component of the system, in order to minimize re-certification costs.

To accommodate this we came up with a topic type design:

• A list of things the reader needed to know: what each input to the system is, and how it is combined with other inputs to create outputs.
• A standard way of presenting this information: a list of every input, every output, and the program that processed inputs into output, and a flowchart with standardized symbols for each input type, output type, and program type.

This type definition also included a list of planning questions that the reader needed to consider when preparing to configure a component of the OS, and a standard form for presenting them.

Everything the reader will need to know to accomplish a purpose

The first step to defining a topic type, therefore, is to develop a list of all the things that the reader will need to know to accomplish a specific purpose. (Defining purposes is a topic for another day.) There are a number of things you can do to assemble this list:

• Read through your existing content noting what information is provided to support the specified purpose. (Be prepared to find that the current content is highly inconsistent in what it provides.) Make a list of all the items of information you find. Remember that you are not trying to describe the type of your current content, just make a list of information that supports a specific purpose.
• Look for items that may be mentioned casually but which occur in many examples of the same type of topic. Perhaps they should be pulled out as a separate item in your list. (For instance, suppose that ingredients in a recipe were only mentioned as they occurred in the preparation steps. Technically this is sufficient, but it would make the recipe harder to use, so recipes pull the ingredient list out and make it a separate item.)
• Perform the task noting all the information that you have to look up or recall as you do so.
• Consult support logs to discover what pieces of information people felt they needed in order to accomplish a task. (Remember that, in some cases, the function of information is to reassure the reader that they are doing the right thing, rather than being strictly functionally necessary. Readers don’t always take instructions on blind faith.)
• Think about the business problem that the reader is trying to solve. Often the information they need is not purely operational, but has to do with how to solve their business problem using your tool or process.
• Get as many people with customer contact as you can to review your list. Development’s input is useful too, but try to get support people, field sales, and marketing involved as well.
• Review each item on your list and ask if this is something the ordinary qualified reader of this topic will already know. (Not the least qualified reader you can imagine, but the ordinary qualified reader of the topic.) Remove those items from the list, but don’t discard them. They may be important elements of a different topic type aimed as a different, less qualified audience.

Standardized presentation

Once your list is complete, it is time to design the order and format in which these pieces of information should be presented.

A good deal of the information in most topic types will  be presented in paragraph form, so a significant part of the order and format of a topic type will consist of a set of headings followed by paragraph text. However, in many cases you will find that there are pieces of information that have been presented in paragraph format in the past that could be pulled out and presented in a more formal way, such as in key value fields or formal structured text formats such as a function signature.

For example, suppose you have found that readers benefit from a list of tools that will be needed to accomplish a certain task. You could model this as a paragraph:

Tools

You will need a pith helmet, a left handed spanner, and a packet of violin strings.

But you can add structure to this element by using a list instead:

Tools

• Pith helmet
• Left handed spanner
• Packet of violin strings

Just doing this, tends to suggest information that might be missing, like sizes, quantities, or specifications of the tools. This could lead you to specify something like this:

Tools

• Pith helmet, large, nylon,1
• Left handed spanner, 50mm, forged steel, 2
• Violin strings, nylon, 1 packet

(This could also be formatted as a table, but in these days where mobile delivery is increasingly important, I recommend you avoid making tables part of your topic design, as they do not display well on mobile devices. From a topic type design point of view, think in terms of structured list items rather than tables. Depending on your writing and publishing tools you may be able to present structured list items as tables on paper and in other formats for online or mobile.)

Yes, this approach will result in a topic that looks more like a reference entry than an essay. This is a good thing. In many cases, your reader will refer to your topic rather than reading it fully. Breaking content out into separate fields with consistent labels will make it easier for them to find the information they are looking for and to comprehend it.

Rather than regarding reference content as something to be separated from the main documentation set, it would be far more realistic to regard all content as a form of reference content in which some fields cannot be effectively reduced to key value pairs and must instead be presented as paragraphs. Paragraphs, in other words, are the structures we use as last resort when more formal structures won’t work. For some types of content, we may have to resort to paragraphs most of the time, but structured data, not free-form prose, should be our default for technical communication.

Benefits of structured format

Making specific lists of required information, and formatting topics by pulling information out of paragraphs and into structured fields has four major benefits:

1. It helps the writer to remember all the information that is needed in each topic of a particular type. The writer does not have to figure out what is needed each time they come to write a topic. The topic type encodes what the organization knows and believes about the reader’s needs and how best to meet them. Writers do not have to figure it out over and over again.
2. It helps the reviewer review the content quickly and more thoroughly. Reviewers routinely miss when information is missing from a long free-form text. They don’t miss when a required field in a structured topic type is missing or incomplete.
3. It helps the reader to find, recognize, and consume the information they need, and, because it helps the writer and the reviewer be more complete and more consistent, it ensures that the information the reader needs is always there. It also helps the reader skip over information they already have in search of the one piece of information they still need.
4. It helps you to reuse information effectively. Consistency and completeness are essential to effective reuse, and content in fields is inherently easier to reuse than content in paragraphs. Continuity and style issues are eliminated with fielded data, and systems can access fielded data at a more granular level to reuse just what is needed.

Benefits of specific topic types

All of these benefits derive from defining topic types that are highly specific to your business. A generic topic type, even one that is supposed to work across all companies in your industry, will not be as specific to your product and your customers and their business problems as one you design yourself. The more specific your topic type is, the more consistent and complete your writers will be, the more thorough and accurate you reviewers will be, the faster your readers will be able to find the right content and act correctly in their task, and the more reliable and complete your content reuse will be.

Benefits are independent of implementation

As noted above, all of this, and all of the benefits that come from defining good topic types are independent of how you implement your writing and publishing systems. This is structured writing in the rhetorical sense of the word and it has nothing to do with DITA or XML per se. You can do this in Word or Frame or Flare or MediaWiki or Notepad.

Supporting types with computable structure

Creating topic types has nothing to do with XML per se. However, the move to topic-based writing does often come hand in hand with a move to XML. XML (and other approaches to structuring content data) can allow you to implement and maintain topic types more reliably. If your are using systems like DITA, SPFE, another form of XML, or another form of markup, you can choose to encode your topic templates as schemas in those markup languages.

This can have a number of benefits, and a number of costs, and must be weighed as a separate business decision. On the other hand, you can choose to stick to generic schemas while writing your content to well defined topic type templates, just as you would in Word or Notepad. Defining and using topic types is not something you do because you are moving to XML. It is something you do because it makes you a more effective technical writing team that produces better, more consistent, more complete content.

More on topic types in future posts.