Structured Writing is Essential for Developer Docs

Tom Johnson wrote a post recently in which he questioned the value of structured writing for developer documentation. Needless to say, I disagree. But Tom and I are not really at odds here. Rather, he means something different by “structured writing” than I do.

Structured writing is about content quality, not publishing

What I mean by “structured writing,” and what structured writing has traditionally meant, is essential for developer docs. But it is something different from what “structured writing” has come to mean in tech comm of late, as we can see from Tom’s argument:

Tech comm traditionally focuses on single sourcing, content-reuse, and structured authoring. This facilitates translation, supports large tech writing teams, and helps reduce time spent formatting.

Most of the APIs, however, aren’t translated. They aren’t delivered as printed material. And they require advanced developer knowledge to properly document. Writing code samples for 4 different languages requires familiarity with code.

…

To thrive in the API doc space, are the skills you need “structured authoring” or expertise at “single sourcing”? I don’t think so. In fact, structured authoring techniques are somewhat antithetical to the needed collaborative authoring with engineers.

Indeed, structured writing today has largely come to mean a specific set of practices designed to facilitate single sourcing (publishing to multiple formats) and content reuse (reusing the same content in multiple information products). These can be powerful cost-reduction strategies in the right circumstances, but, as Tom says, there is not a lot of scope for either of these techniques in typical developer documentation.

But developer documentation does contain a lot of structure, and a lot of precise information that has to be correct and complete. Developer tools are often not discoverable the way physical hardware or end-user software is, so incomplete or inaccurate developer documentation can be highly damaging to the usability and reputation of an API or other developer tools.

Structured writing, correctly applied, can do a huge amount to ensure the completeness, correctness, and consistency of content. This is not about cost reduction, but about quality improvement (though if you do it right you will get the other things as well).

Technician’s doc needs different from consumer’s

In his post, Tom argues that the future of tech comm lies with developer documentation rather than consumer documentation. In a comment, I suggested that the future lies in documentation for technicians of all kinds, not just developers. How is documentation for technicians different from documentation for consumers? First and foremost, it contains far more reference material. Consumer documentation is mostly discursive; documentation for technicians is mostly reference. And references are structured.

Rhetorical structure of content

Reference material has what (in my book) I call “rhetorical structure”. That is, each entry in a reference has the same format: the same information in the same fields with the same headings in the same order. Thus for a simple API routine, you might have a function reference entry that looks something like this (from the Android API docs):

There is a lot of rhetorical structure here. We can begin with the top line:

public boolean setName (String name)

This is a function signature, a structured piece of code in which each term expresses something particular. The basics of the structure here are positional. The first term, “public” expresses the visibility of the function; the second, “boolean”, expresses the type of its return value; the third, “setName” expresses its name; and the part in parentheses lists its parameters by type and name.

This is followed by a general description of the function, and then by subsections on the parameters and the return value — a structure you will find in every entry. However, this is not the limit of the rhetorical structure of this entry. Though it is not called out with a subheading, the final paragraph of the description,

Requires BLUETOOTH_ADMIN

is definitely a piece of structure, and one that you will find recurring in many other entries in the same UI reference. It expresses an important piece of information in a consistent format. Should it be called out with its own heading, or at least in a labeled list format like this?

Requires: BLUETOOTH_ADMIN

I think so. But that is just a presentation decision. More important is the structure. Does this piece of information appear in the same place in the same form in every entry so that the reader can readily find this information when they need it?

There is a more subtle, but equally important structure to be found in the rest of the description. Consider the first pargraph:

Set the friendly Bluetooth name of the local Bluetooth adapter.

The very first paragraph of the description states what the function does. Is that something we think should be consistent across all the API reference entries? I think so.

Might some writers be tempted to lead with something else on some occasions? They might. For instance, some APIs may exist for obscure reasons, and the writer might be tempted to lead with an explanation of the circumstances that call for the API, rather than starting off by stating what the API does.

Should they yield to this temptation? I think not. What they should do, I believe, is lead with what the function does, and then give the explanation of why you might want to do this. Why? Because consistency in the format of an API reference entry helps the reader use it efficiently, and also because (as I will discuss shortly) it helps ensure that writers cover all the information they are supposed to cover each time. (Is there a place where leading with the Why? would be appropriate? Yes: in a pathfinder topic that helps the reader connect their business problem with the appropriate bit of technology. Different topic types serve different purposes.)

The second paragraph also states something that is likely to recur across many APIs:

This name is visible to remote Bluetooth devices.

This deals with the scope of impact of the API. What is affected by the action of this API? This is vital to the reader understanding the consequences of using the API. It is something you need to know about every API you call.

The third paragraph also deals with an issue that will be consistent across many entries: what values are valid to pass to the API, something every programmer needs to know to call the API correctly:

Valid Bluetooth names are a maximum of 248 bytes using UTF-8 encoding, although many remote devices can only display the first 40 characters, and some may be limited to just 20.

The fourth paragraph deals with how system state may affect the way the API behaves:

If Bluetooth state is not STATE_ON, this API will return false. After turning on Bluetooth, wait for ACTION_STATE_CHANGED with STATE_ON to get the updated value.

This is also a piece of information that is important for every API.

And that is it: every paragraph in the apparently unstructured description turns out to have a specific function that likely should be repeated across every entry in the API reference. Each one deals with an aspect of operation that may apply to any API, and that the programmer calling any API may need or wish to know about.

Do these elements actually occur consistently in every entry in this API reference? Probably not. Are the issues addressed in other entries that should be addressed in this one as well? Probably. Would this reference be more complete, more consistent, more accurate, and more useful if these matters were treated consistently across every API entry? Almost certainly.

While this API reference entry does have some explicit rhetorical structure therefore (the explicit structure common to most API references) even a cursory examination reveals much more implicit rhetorical structure, and raises several questions about the completeness and consistency of this and other entries.

Can human beings be consistent?

Can we rely on writers, and on the API developers who supply them with the information, to consistently include all these implicit pieces of rhetorical structure — and the important pieces of information they represent — without explicit guidance?

Personal experience both of creating and of using API references tells me that the answer is definitely no. Even the most skilled and dedicated developers and writers cannot be this consistent without external aids. In fact, I have seen more than one occasion in which applying a systematic structured approach to documenting an API has revealed significant design problems in that API and resulted in significant redesign and reimplementation.

This is entirely consistent with what we find in other skilled trades. In any complex task requiring consistency and precision we find a profound reluctance to depend on human memory and consistency alone. Rather, trades of every kind rely on checklists, jigs, tests, forms, and other devices to assist the technician in getting the task right each time, and to assist their supervisors in detecting and correcting issues.

In some factories, for instance, a system monitors to see if the technician’s hand breaks the beam over each bin on the parts shelf during the assembly of a product. This largely eliminates errors in which a technician forgets to install a particular part on one product. It is the kind of error that is easy for even the most experienced technician to make — a moment’s distraction is all it takes — and one that is expensive to correct if not caught early. Humans need help to be consistent and to produce the highest quality on a consistent basis.

This — not publishing or content management, necessary as they are — is the role that structured writing was meant to play in technical communication: to provide the guidance and the audit capability that allows professional writers (and the engineers that they work with) to perform at a more consistent level of quality and consistency.

Certainly the programmers that we work with will find none of this unfamiliar. They use a whole raft of structured tools and techniques to improve the consistency and quality of the software they create. They also use a great deal of automation to perform tedious and error prone tasks. They can therefore easily appreciate what structured writing is about and can participate effectively in it — providing you don’t ask them to deal with complex publishing and content management issues that they care nothing about.

Start by defining rhetorical structure

What is the first step to implementing structured writing for developer documentation? It is not to reach for XML or DITA or a CMS — those are just implementation details, and not the only implementation options available. The place you start is with the definition of the rhetorical structure of your topics. As I noted in my post on Designing Topic Types, a topic type is a pretty simple thing. It is just a list of the things that a person needs to know to accomplish a particular purpose, and a standardized order and form for expressing those things. In that post, I outlined a basic process for determining what is required and establishing an appropriate order and form for the content.

Then figure out how to provide guidance, audit, and automation

Once you have mapped out the rhetorical structure — the topic type — you can think about how you want to provide the guidance and the audit capability that will help authors and other contributors comply effectively to the desired structure. Using a computable structure such as XML can help greatly here, by providing opportunities for automating tedious and repetitive tasks and allowing for automated auditing. If used correctly, it can also be used to take the publishing and content management issues entirely out of the author’s domain, which simplifies the task of authors and contributors, leaving them more time to focus on content, structure, and the user’s needs.

However, it is the rhetorical structure that is of the first importance, and you can express this in many other ways, such as by wiki templates, relational tables, or FrameMaker templates. You can even do it through an external style guide, though the further removed the guidance is from the place the work happens, the less effective it will be. (XML or a database structure can provide the alarm when the hand fails to break the beam above a parts bin; a style guide cannot.)

Structured writing essential for both reader and writer

There is a great deal more that could be said about how to implement these things in a computable structured writing system, but that is for another day. The point for today is twofold:

• When you write for technicians, you write for people whose tasks are complex, and which require a high degree of precision and accuracy. This requires precise, consistent, complete, and accurate documentation. Structured writing helps you provide that level of quality in the documentation you create.
• The task of creating such documentation is itself a complex one that requires a high degree of precision and accuracy. Structured writing provides the guidance and the validation that all humans beings require to perform complex and precise tasks consistently and correctly. A formal structured writing process is necessary to provide the level of documentation that the job of a technician requires.

Want to talk more about how structured writing approaches can improve the consistency, quality, and completeness of your developer documentation? Drop me a line. Let’s talk.