Outro: What You Did and What’s Next
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.
What you did
Congratulations 🎉 You just drafted, revised, and published a piece of technical documentation that will help your reader’s get the most out of your app. And you should feel confident in this statement because your technical documentation is:
Specific to your reader’s goal
Organized and structured
Accurate, consistent, and concise
Polished because you tested and edited it
But as you worked on your document, you might have thought:
It’s clear I need to create more documents… but how should I organize them?
All this is great for new documentation… but what about existing documentation?
I’m sure there’s more to learn… is there a course on technical writing?
Well, fret not!
What’s next
How to organize a collection of documents
Organizing a collection of documents under labels is known as information architecture (IA)¹. To start, use this basic IA for your app. Notice how the labels mirror the content types. For demo purposes:
Directories or folders have a forward slash like
/a-directoryFiles or pages use the format
a-page.ext
Basic IA ------------------------------------ get-started.ext /tutorials ↳ a-tutorial.ext ↳ another-tutorial.ext /how-tos ↳ a-how-to.ext ↳ another-how-to.ext /explanations (or /topic, /concepts) ↳ a-concept.ext ↳ a-topic.ext /reference ↳ an-element.ext ↳ another-element.ext troubleshooting.ext support.ext glossary.ext
Notice how there’s a Support page. A support page details how readers can reach the team who supports the app. This page isn’t a content type, but it’s strongly recommended in any IA.
How to revise existing documentation
Revising existing documentation is a little tricky because a simple, “Maybe I’ll just move this here…” can morph into an “OMG, I need to rewrite every. single. word.” To prevent this, I recommend the following approach:
Determine the target audience for the documentation; doing this will make your content updates much more focused.
Determine the goal of the documentation; this will help you determine the true² content type.
Is it to get started? → Getting started
Is it to teach or demo something? → Tutorial
Is it to provide instructions for a specific task? → How-to
Is it to explain a topic or concept? → Explanation
Is it to provide specifications about a software element? → Reference
Is it to provide solutions for errors? → Troubleshooting
Reorganize the existing content; use the skills you learned in Part 2.
Update the existing content; use the guidelines you learned in Part 3.
Revise and publish the updated³ content; use the process from Part 4.
The approach doesn’t include creating a glossary – this is on purpose. In my god-awful experience, the minute I decide to create a glossary, my updates to a single piece of technical documentation balloons across the entire documentation set and much more. 😩 Creating a glossary and updating any related documentation should be a separate, focused effort.
How to expand your technical writing skills
Here are some of my favorite resources; also recommended by many peers.
Technical Writing for Developers; a free, self-paced course by Google
Docs for Developers: An Engineer’s field guide to Technical Writing; great, approachable book
Modern Technical Writing; “Don’t write” as the third heading in the table of contents had me verklempt
If you’d like to practice your writing skills in the real world, I think Google Season of Docs is a fantastic way to get started with the open-source community.
Another way to expand your skills is through the technical writing community. I wholeheartedly encourage you to join the WriteTheDocs Slack network even if you’re shy about your skills. I’m always learning and relearning by the discussions in the various channels. I’ve also sent technical writing bloggers such as Tom Johnson emails about challenging documentation projects and have received thoughtful, sincere feedback.
As long as you’re engaged in the technical writing community, you’ll still grow as a technical writer even if you’re not actively writing. 🤩
Last words
I hope this tutorial on technical writing was approachable and amusing. If you’d like to know more about the field in general, or if you’d like to befriend someone who loves Oxford commas and can debate the logic behind it, feel free to send a note!
I have to end this series with a note to others: Youenn Pennarun, Casey Brown, Robb Romans, Eva Parish, Mark Marchione, and Tom Drapeau for working your magic to make this happen. You’re all rock stars 🕺for helping me with words #englishishard
¹ That’s the definition I provided for this tutorial – there are many definitions for information architecture (IA). It’s because the field intersects technology, design, and science and merits its own World IA Day. For what it’s worth, we learn to organize and label something before speaking – who knew?! (Thank you Abby Covert for making IA less intimidating.)
² In my experience, most existing documentation tries to meet more than one reader’s goal. When this happens, documentation is verbose, difficult to scan, and not specific. This is why a reader may become frustrated with documentation, and in turn, the app.
³ After you update a single piece of existing documentation, you may be beset with a strong desire to revamp the “whole shebang”. Documentation revamps are better known as content inventory and audits. The Nielsen Norman Group has a thorough article on the process.
