Modern Technical Writing: An Introduction to Software Documentation

by Andrew Etter

Exceptional technical writers are force multipliers within the software industry. Great documentation makes new hires productive in days instead of weeks, prevents thousands of calls to customer support, is the difference between crippling downtime and rock solid stability, and inspires true, fervent love of development platforms.

Identify what the audience actually needs to know, and include only that.

Technical writers, first and foremost, are testers and researchers. Your job is to know what people want to achieve and precisely how to achieve it. Communicating that knowledge is the last step of the process and really shouldn't comprise more than 10% of your time.

Your testing should be centered around making you smarter. Once you have a complete grasp of how something works, you can stop. Unlike a tester, you don't have to go any further.

The learning process is time-consuming, so don't be discouraged if your measurable output is essentially nil for days or even weeks after moving onto a new project.

Talking to people is an art. A tester might want to gripe about a useless or buggy feature, whereas a developer might anxiously justify architectural decisions. A product manager probably wants to discuss long-term vision and will be upset if you didn't schedule a meeting, whereas a salesperson might be perfectly happy to chat about user frustrations from adjacent bathroom stalls. A good rule of thumb is to treat everyone as busy individuals whose time is valuable, but another rule of thumb is to break this rule and be more of a jerk if an essential employee isn't giving you the information you need to do your job. Tailor your approach to the person, come prepared to meetings, batch your questions into related sets rather than bothering people every twenty minutes with individual questions, and thank everyone for their time.

Users are people who just want to achieve something with an application, whether it's resizing an image, creating a spreadsheet, or sending an email. Users are typically concerned with inputs and outputs.

Administrators install and configure applications. I'm not just talking about server administrators or people with administrator permissions on a computer, but anyone whose concerns are setup and maintenance. How much disk space does the application server fill over time? Where are the logs located? How do you recover data in the event of a crash? What's the simplest way to perform backups?

Developers extend applications or interfaces with code. They want to improve some aspect of an existing application or build something new. More than anything, they need reference materials, short tutorials, and code samples.

What is this product? Why would anyone want it? These two questions are incredibly challenging for the average technical writer, a group of people much more focused on how than what or why.

How does this product fit into a broader ecosystem, if at all? Does it have any dependencies? The answer to this question can be a single sentence, an architecture diagram, or a complex discussion of the various components necessary to create a coherent product stack.

How do I install the product? What are the basic configuration options, if any?

What does a simple, start to finish operation look like? This section can be anything from a pictorial walkthrough to a functional code sample—to be clear, not just a couple snippets—but whatever it is, it should take the user from nothing to something. It should be meaty enough to convince readers that they've learned something.

Whenever possible, don't write from memory. Verify content as you write it. If the documentation involves shell commands or code snippets, copy and paste them after validating that they work.

Bias towards including headers, tables, lists, diagrams, and images. These additions make your writing more approachable and simpler to scan than paragraph after paragraph of prose.

One of the most important functions of a technical writer is to record changes to a product. Good change logs convince people to upgrade, inspire confidence in the direction of a product, and help developers take advantage of new features.

More than anything else, change logs should be terse, minimalist, and eminently scannable.

Hosting your content on a website gives you the power to fix inaccuracies almost instantly and keep your content in sync with the latest software release.

Shipping an HTML help system with the software itself is barely better than PDFs.

people really will contribute if you just let them.

Publishing should not be a special event. It should not be challenging. It shouldn't require anything more than a quick sanity check and a glance at the build log. Something about your process is broken if you need more than a minute to verify that content is ready to post to a production website.

Even simple automation is effective, like a Cron job that checks out and builds the documentation every hour, writes the build log, and posts the resultant content to an internal staging server.

Documentation with any sort of lifespan needs to be kept in version control, which Word's DOCX file format (a compressed collection of XML files) actively opposes. Documentation should live online, and Word's abysmal HTML export is totally unsuitable for creating websites. You have to style content in Word as you write it, rather than taking advantage of the natural separation of content and style, of HTML and CSS.

If you have the opportunity to store your documentation in the same repository as its corresponding product source code, strongly consider doing so. The approach has some real appeal: Documentation and code branches stay in sync. Developers are more likely to contribute if they don't have to clone a separate repository. Of course, this approach also has some cons: If a repository is large (e.g. 2 GB), checking out the entire repository just to access the 40 KB ./docs directory can dramatically slow down documentation builds. Onerous commit hooks and pull request submission policies, designed to keep a code base stable, can make even simple documentation changes a chore.

The core idea here is that you should break your writing into bite-sized pieces, often called topics, none of which overlap in content. Doing so means that if things change—and things always change—you only have to update the documentation in one place. Many topics are short, whereas others are quite long. What topics should be is relatively complete in their discussion of a particular subject.

for the most part, linking liberally, arranging topics in a sensible way, and trying to adhere to a single source model is a good idea.

The worst duplication sin of all is to store similar copies of the same documentation in version control. The root cause here is typically the desire to have one version for coworkers and another for customers, and it inevitably leads to a maintenance nightmare.

Find a designer and ask for help with colors, typefaces, font sizes, page width, and spacing. This customization is your chance to differentiate your content from the thousands of ugly, disorganized sites of the world, so don't just use the default theme. If you don't have the skills to do this customization yourself, you might need to hire someone. It's that important.

If you aren't keeping an eye on documentation metrics, you're making a huge mistake. User research is wonderful, but knowing exactly which pages are most popular, your site's bounce rate, and common behavioral flows are all invaluable. Create a Google Analytics account, add the provided tracking code to your static site theme, and check the numbers regularly.

Learn everything about a subject. Write down exactly what an audience needs to know and no more. Make the content beautiful, discoverable, scannable, and searchable. Consider everything a draft, and iterate relentlessly. Make contribution simple.