Part 3: Draft Content That’s Accurate, Consistent, And Concise
KEY TERMS
-
In this tutorial, an app represents a single piece of software that’s provided for others to use. This could be a mobile app, a web app, a microservice, a database, an API, a Figma component library, a React component library, a script, and so forth.
-
The group of people who are most likely to use the app. For example, if the app is an API, the target audience is likely to be only developers. Whereas the target audience for a Figma component library is designers.
-
Any piece of writing that includes technical writing.
In my opinion, creating good headings and organizing them in a way that’s helpful to readers is much more challenging than drafting content. So pat yourself on the back for completing Part 2 of this series and making it to Part 3. 👏 👏 👏
However, there are three things that undo exceptional headings and structure in technical documentation: content that is inaccurate, content that’s inconsistent, and content that’s inflated.
ACCURATE CONTENT IS THE GOLDEN RULE OF TECHNICAL WRITING
But what is inconsistent and inflated content? Well, when technical writing includes:
Different terms for the same thing; for example,
app,application,web app.A single term for different things; for example,
appfor web and mobile apps.New terms without definitions; for example,
media alternatives.Personas without definitions; for example, is a
useran internal user or an external customer?
Readers will have more questions – not fewer – as they use the technical documentation. This is not the goal of technical writing.
And when technical documentation is inflated, or verbose and long-winded, readers may not read the important information they need. Can you guess why? It’s because readers do not read on the web – they scan.
So how to draft content that’s consistent and concise?
KEEP A GLOSSARY THEN KEEP IT SIMPLE, KEEP IT SHORT,
KEEP IT TO THE NEED-TO-KNOW¹
Glossaries are underrated in technical documentation. They help you draft consistent content which is necessary for content that’s clear and easy to understand. You’ll learn how to draft one in the “Try it out” section.
To keep the content nice and trim, I’ve provided guidelines for each content type and its typical headings. Remember, the content types don’t use every listed heading. As a reminder, I haven’t included guidelines for Onboarding guides and Runbooks since they’re specific to teams.
Info: The guidelines include mock content for the mock command line tool CatFactz. CatFactz generates cat facts to entertain users when they can’t take a cat nap. 🐈⬛ The target audience for CatFactz is developers.
Getting started guide
Getting started guides are like a first impression. When it comes to content, three things often turn readers away:
Complex, technical language
Blocks of content – multiple, long paragraphs
Steps with sub-steps, with sub-sub-steps…
The guidelines in the cheat sheet try to prevent anything that might turn a reader away.
See the cheat sheet for a getting started guide.
Tutorial
Readers use tutorials to learn a new skill with an app. They’re not using tutorials to become an expert – that comes through experience. 🤓
Whenever I have to write a tutorial, I always think of a time when I used a tutorial. The best ones had concrete steps, each with a specific task and an outcome or a result. The worst ones overwhelmed me with detailed abstract concepts or justifications. To the point where I didn’t want to use the app.
This is why the guidelines in the cheat sheet focus on what’s essential to complete the tutorial – nothing more, nothing less.
See the cheat sheet for a tutorial.
How-to guide
How-to guides are like recipes. My favorite recipes² give you exactly what you need to create a beautiful dish. Recipes that provide a neverending preamble, long notes for every ingredient, and freeform instructions leave me wondering why the author published the recipe in the first place…
The listed guidelines will help you draft a how-to guide that’s as good as your favorite recipe³.
See the cheat sheet for a how-to guide.
Explanation guide
It’s tempting to include everything – app history, specifications, and instructions – in a single explanation guide, but I do not recommend it. Can you guess why? “Readers scan on the web, they don’t read.” #tryingtodrivehomeapoint
A good, concise explanation guide is limited to a single topic. Hence the specific guidelines in the cheat sheet.
See the cheat sheet for an explanation guide.
Reference guide
Because the reader’s goal is to find a fact or specification as quickly as possible, reference guides have to be easy to scan. This is why the guidelines in the cheat sheet specify h3 headings, tables, and bullet lists more than the other content types.
See the cheat sheet for a reference guide.
Troubleshooting guide
Similar to reference guides, a reader is looking for a solution to their error with the app quickly. The guidelines in the cheat sheet ensure the content is easy to scan or find, and neutral in tone. A troubleshooting guide shouldn’t try to befriend the reader when they’re frustrated.
See the cheat sheet for a troubleshooting guide.
Try it out
Keeping your target audience in mind, create a glossary for your content type. For reference, visit the glossaries for GitHub, Shopify, Flutter.
Make sure you list and define the following:
Any personas that may confuse the reader. For example, who is a
userexactly? Is it a subscriber or a developer who consumes an app?Any terms or phrases that are specific to the app.
Any terms that may have multiple meanings in your field. For example,
responsive designis often thought of asadaptive designbut they mean different things.Any properties, parameters etc. that may be used across multiple pages.
Draft content for each heading you created in Part 2; use the guidelines listed in the cheat sheet for your content type.
If you can, use an online word-processor like Google Docs to start. Tools like Google Docs allow reviewers to suggest edits that span across multiple sentences and move phrases around – this is difficult⁴ to do in a pull request.
As you write, keep these tips in mind:
“Websites require a unique style of writing. Novelists paint a picture with words. Reporters report the news with dramatic flair. Academics explain complex ideas in context with citations. Web content writers share information as succinctly as possible.”
“Try reading parts of your document out loud, or at least mouthing the words. Does it sound natural? …If you come across a sentence that’s awkward or confusing when spoken, consider whether you can make it more conversational.”
“Plain language is for everyone, even experts.”
Up next
Part 4: Test, edit, and publish content. The title says it all, but there is so much more to this process. I break things down with a cheeky acronym, A-TEAM: Away, Test, Edit, Approve, Merge.
¹ Thank you Sandra Lee and Semi-homemade Cooking. You saved us during the pandemic.
² If you’re wondering, my favorite recipes for appetizer, main, and breakfast, dessert.
³ Please reach out with your tried and tested recipes! If I had a do-over button, I’d go to cooking school.
⁴ Tom Johnson, a senior technical writer at Google, has this to say “Tools like Google Docs work much better at facilitating conversations around specific points in your content.” – I'd Rather Be Writing.
