Principles of Technical Writing
Kai Alvason, PhD
Designing the Customer Information Experience for the 21st Century | Documentation, Support Communications, and Customer Education
“Docs as Code” and the Shifting Role of the Technical Writer
Over the past several years there has been a significant “shift left” in the world of technical writing, where, through the adoption of “docs as code” models of content management and publishing, more responsibility for the production of technical documentation has fallen on developers. The rationale is that, since they are closest to the product, they are in the best position to document it, and so the tools and skills for technical writing roles have shifted focus away from DITA, XML, and wikis, to Git, markdown, and code proficiency. Along the way, many of the core principles of quality technical writing have been left behind, much to the detriment of the content that is being produced, and strong anti-patterns have emerged. For example, the “scroll of death” that was anathema in the early days of online content development is now common, and the usability of documentation to accomplish tasks and gain information has been severely impacted. Examples of frustrating and unusable documentation are legion, though I will refrain from calling out any specific ones here, since you never know who you’re going to interview with in the future.?
In this article I will lay out a few principles that have been part of my style guides for over a decade. With these, I hope to kindle a wider conversation about the objectives of technical documentation, the role of technical writers in the software enterprise, and how those of us who are not developers can contribute to the success of products and enterprises through technical communications.
Sources
The principles and guidelines in this article are derived from several sources that span domains from cybernetics to literary criticism to technical writing, as explained throughout this article. For those interested in some direct sources, these texts are highly recommended:
Microsoft Manual of Style The classic reference guide for technical publications
Designing Web Usability by Jakob Nielsen. One of the first examinations of writing for online media, written by a former Distinguished Engineer at Sun Microsystems
The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skill (Technical Communication, Multimedia, and Information Systems) by John M. Carrol. An introduction to the "minimalist" approach for instructional design for computer systems
Minimalism Beyond the Nurnberg Funnel (Technical Communication, Multimedia, and Information Systems) John M. Carrol (ed). Essays expanding upon the concepts in the original book
The Act of Reading: A Theory of Aesthetic Response by Wolfgang Iser. An examination of the cognitive and interpretative processes that constitute the act of reading
DITA Specification 1.3 The OASIS specification for the Darwin Information Typing Architecture v1.3
Principles of Technical Writing
Reduce Cognitive Load
In cybernetics, the world can be reduced to three components: environments, systems, and information. Systems can be organisms or organizations, individuals or cultures. Environments are the container that systems find themselves in, and information is the means by which systems interact with their environment. A simple example is an individual (system) who is moving around a city (environment) by using a map, landmarks, and his or her own general understanding of city environments (information).
As anyone who has traveled abroad knows, finding oneself in a new environment where it is difficult to parse information, is extremely stressful. Launching an application for the first time, when the user has a very specific task they want to accomplish, can also be stressful. The first thing a user will do is situate themselves by finding familiar landmarks in the interface, and a mark of good interface design is the availability of "affordances" that the user can immediately recognize. The interface, however, is only the first piece of information that users will seize upon. Travelers around a city will certainly use familiar landmarks to orient themselves, but they will also use a map to guide them to places they don't know about, and to help them understand the relationship of one point to another.?
In the application environment, technical documentation is the map that helps the user find their way around and accomplish their tasks. The application's interface and technical documentation can be thought of as two different channels, carrying different types of information, in a comprehensive user information system.
Quality technical documentation reduces the user's cognitive load, reduces their stress in a strange environment, and helps them get things done. Along the way, it also reinforces a positive experience with the product, and with the brand. After the interface, technical documentation is the second main point of contact a customer has with a product, and one that has the potential to profoundly influence their overall perception of its quality and usefulness.
At my Amazon orientation, i was surprised that this concept was central to a video from Jeff Bezos. In it he described the cognitive load imposed on a user by an elevator with an odd layout for the floor buttons. Reducing cognitive load is at the center of Amazon's eCommerce experiences, and is responsible for much of their success.
Reader Obsession
A common issue with technical documentation is the assumption that the writing is what matters, that the work of getting words onto a (virtual) page is the main task for documentation. In fact, the most important act is not the writing, but the reading of the documentation.
From the point of view of the reader, there are three aspects to quality documentation:
When writing technical documentation, always read it from the perspective of a customer who is trying to quickly locate and use a specific piece of information. Aim for simplicity of explanation, clear direction, and formatting and structure that helps the reader quickly scan and identify important information.
领英推荐
One Idea, One Topic
As described in the Wikipedia article, “The Darwin Information Typing Architecture (DITA) specification defines a set of document types for authoring and organizing topic-oriented information, as well as a set of mechanisms for combining, extending, and constraining document types.[1] It is an open standard[2] that is defined and maintained by the OASIS DITA Technical Committee.[3]” The DITA specification includes a markup schema for semantic tagging of document components, and defined components and structure for four types of information topics: Concepts, Tasks, References, and FAQ. These topics in combination with one another are used to construct the “topic set” for any type of product or feature, and DITA is used in the production of technical information across a wide variety of domains, including manufacturing, software, and automotive manuals.?
For our purpose, the most important aspect of DITA is the concept of “one idea = one topic.” This topic-based approach improves the discoverability of information by enabling granular tuning of SEO for the product documentation, while the naming conventions associated with each topic type can help customers understand the contents of the topic without needing to read it. It also makes it easier to add and update information in the future, since new information can be incorporated by creating a new topic, and the need for updates can be localized to single topics. In the DITA approach to information, the long, scrolling page that contains many types of information is an anti-pattern because it increases the cognitive load on the customer to find and use information, and because it complicates content management into the future.?
Many Minds, One Voice
The main challenge of collaborative documentation is recognizing that while many minds are contributing their expertise to the project, they need to speak with one voice to the reader. The purpose of using templates and the DITA documentation standard is to provide a consistent structural foundation for the documentation. The purpose of a style guide is to provide those many minds with a consistent voice, and with a consistent approach to information presentation.?
Tone: Your Very Smart Friend
Much technical writing suffers from poor readability and usability because it takes an overly formal tone, and attempting to be very formal also often results in complex sentences, use of the passive tense, and indirect reader address.
When writing technical documentation, take on the role of a very smart friend addressing another smart friend. You can assume that your smart friend is a peer who is already familiar with what you're saying, but needs some clarification on specific points. You can also think of yourself as a professor who is addressing an advanced student. Keeping the audience in mind, along with the role you are taking in relation to them, will often help the writing process as well. If you find yourself using a lot of "whereas," "thus," and "therefore," and the passive tense, you're probably taking too formal a tone. Don't be afraid to address the reader as "you," and the phrase "you can" should constantly recur in your documentation, since the very point of it is to enable the reader to do something.
Keep it Minimal
You should be able to read a good technical topic with just a glance, because the information is clearly laid out, and there is little "noise" in the language or presentation. One of the most common anti-patterns in contemporary technical documentation is describing the steps of a task in a narrative format, rather than in step-by-step instructions. The narrative format makes it difficult for the reader to discern what the individual steps in the task are, as well as what elements of the UI are involved. If there are related tasks or information, document those in a separate topic and link to it as necessary, rather than interrupting the task flow.
Before
Next, specify the LDAP authentication server address and port number, the version and vendor for your LDAP server, and the DN base search information. Supported versions and vendors are available on the drop-down. Import the LDAP server certificate, and optionally test the connection before saving the configuration. The Base Search DN strings are used to look up the user(s) in the central directory. For example, for a user named "John Smith" the strings could be "cn=John Smith, ou=users, ou=engineering, dc=Wonka." The table below details the settings for supported LDAP authentication servers and protocols.
After
Design for Search
Most documentation sites are organized like books, with sections, chapters, and pages organized hierarchically. However, this is an outdated metaphor for representing online information. Instead of reaching for a book and scrolling through the table of contents to find content, most users will enter a search term in Google, click through to a promising result, and then follow links internal to that page for other information of interest.
For this user experience, the hierarchy of topics is less important than careful design of the page title and introductory paragraph for search engine optimization, and then making sure the user can quickly locate the information that they are looking for within the page. Following consistent structure for task, reference, and concept topics enables users to quickly understand the type of content they are looking at without reading it, while consistent use of bulleted and numbered lists, and link and text formatting, helps draw their attention to specific aspects of the content.
Information About the Product is Part of the Product
Developing the technical information about a product or feature should be part of the overall product management cycle, from UX mock-ups to published “docs” to sales and marketing communications. In the world of enterprise software, the product itself is a black box, and the only way a customer can learn about its features and how to use it is through the layers of information built around it. Every Product Requirements Doc should include scoped requirements for the information that will be required to support the product, and a plan for its development alongside the Engineering development.
Principles and Style
A style guide is often misunderstood as a set of rigid grammar rules that must be followed. However, a style guide is more a matter of implementing principles in response to questions that arise during writing ("how should I format something" being one of the most common), than grammar. Any enterprise can set its own style for its technical communications, as long as they also have principles that they can use in making decisions about that style. In this way, these principles of technical writing are like Amazon's Leadership Principles: not rules to be followed, but tools to use in thinking about the production and goals of technical communications.