Lauren Schaefer 0:00
If you’ve found yourself needing to write documentation and just staring at the blank page not knowing how to get started. Yeah, we me neither.
Lauren Schaefer 0:25
The first time I sat down to write official product documentation, I struggled. But I pushed through the discomfort. And with the help of some really high quality reviewers, I published my first piece of official product documentation. Now, I still don’t love writing documentation, but I have gotten better at it over time. So today, I’m going to be sharing with you seven best practices for writing documentation. Let’s jump right in.
Lauren Schaefer 0:55
First up, read some of the docs.
Lauren Schaefer 1:00
If you’re adding on to an existing set of documentation, start out by reading it. If you can get through all of it in a reasonable amount of time, read all of it. If not read the important pieces like the introduction, the Getting Started Guide, and something similar to what you’ll be writing.
Lauren Schaefer 1:18
Look for patterns and how the documentation is structured. And consider how you can follow that structure in your writing. Familiarize yourself with key terms and the level of detail provided as you want to match these aspects in your new documentation. In many cases, you’ll want to aim for your documentation set to be so cohesive, that it will seem like it was written by one person.
Lauren Schaefer 1:44
If you find something confusing, or that can be improved while you’re reading, take a note or open a ticket. Don’t get sidetracked into fixing everything right away.
Lauren Schaefer 1:54
If you’re writing a new set of documentation, and you don’t have the luxury of reading existing docks, do a light read of documentation for similar projects. Think about what you like and what you don’t like. And this will give you inspiration as you start writing. So Best practice number one, read some of the docs.
Lauren Schaefer 2:16
Best practice number two, identify what needs to be documented. And I’m not talking about just that high level topic. I’m talking about the details.
Lauren Schaefer 2:28
What concepts do your readers need to understand? Do you need to explain these concepts or link to other resources that explain them?
Lauren Schaefer 2:37
What prerequisites will your readers need to complete before beginning?
Lauren Schaefer 2:42
What steps will your readers need to take?
Lauren Schaefer 2:45
What will the reader learn or accomplish after reading rotation?
Lauren Schaefer 2:52
And what versions of the software does the documentation apply to? If you’re documenting how two pieces of technology work together? What versions are supported?
Lauren Schaefer 3:02
The details
Lauren Schaefer 3:05
the details.
Lauren Schaefer 3:07
If you’re not already an expert on the details, dig in to learn them. Perhaps you do urge. Perhaps you try the steps yourself. Perhaps you ask an expert questions to do a combination of all three. Keep notes about things that confuse you or where you get stuck. Be sure to detail the steps of first time user, because the experience may be different in subsequent tries. If you’re already an expert on the topic, consider what you know that your readers will not walk through any session. environment. It’s so easy to forget that you previously installed something months ago when you tried it for the first time yourself. So, identify what needs to be documented.
Lauren Schaefer 4:03
Best practice number three, learn about your reader. Now if you’re lucky, some already create detailed personas. If you’re writing internal documentation for your team, you might be lucky enough to know your readers personally.
Lauren Schaefer 4:19
Try to answer the following questions about your reader. What’s your reader trying to accomplish? What do they already know about the topic?
Lauren Schaefer 4:29
What concepts and terms will be new to them?
Lauren Schaefer 4:33
How does your reader want to find the information that they need? So Best practice number three, learn about your reader.
Lauren Schaefer 4:42
Now before I move on to best practice number four, I want you to pause and think about your favorite technology. Maybe it’s a framework, maybe it’s a library, maybe it’s a programming language or maybe it’s a tool. You have something in mind
Lauren Schaefer 4:58
now
Lauren Schaefer 5:00
Think about their docs.
Lauren Schaefer 5:04
Have you read their entire set of documentation?
Lauren Schaefer 5:08
Chances are good that you’ve not. So Best practice number four, right? So your Doc’s are skimmable. People rarely read the entire set of documentation from start to finish. Instead, they’re going to jump around find a page they think is going to have the information they need, skim it and starting first with the headers and then drilling into any sections that look relevant.
Lauren Schaefer 5:32
So here are two pages of documentation that contain the exact same information. Do you prefer the page on the left or the page on the right?
Lauren Schaefer 5:43
I’m going to take a guess that you prefer the page on the right.
Lauren Schaefer 5:47
Why will the page on the right is formatted for skim ability.
Lauren Schaefer 5:52
The first thing you might notice is that that page has headers that break up the sections.
Lauren Schaefer 5:59
The Note has color highlighting to separate it from the rest of the text. And the bulleted lists help break up long chunks of information into easy to digest phrases.
Lauren Schaefer 6:11
So here’s some tips for writing so that your docks are skimmable.
Lauren Schaefer 6:15
Use descriptive headers that allow your reader to quickly determine if a section will provide the information they are looking for.
Lauren Schaefer 6:24
Right in short paragraphs focused on a single idea.
Lauren Schaefer 6:29
long paragraphs are just harder for the reader to parse. short paragraphs are also easier to translate to other languages.
Lauren Schaefer 6:39
Use bulleted lists to share groups of information
Lauren Schaefer 6:43
and use numbered lists to share sequential or ordered information. Numbered Lists are exceptionally helpful for steps in a tutorial. So in summary, right, see your Doc’s are skimmable.
Lauren Schaefer 6:58
Best practice number five, read the style guide, or select one. Have you ever wasted time debating with a teammate and a pull request about the formatting that should be used? It’s painful, right?
Lauren Schaefer 7:14
Just like a development team creates code formatting guidelines, your team can create a style guide for your documentation. A style guide is just a document that provides rules and guidelines for consistent writing. When you write documentation, you need to make a bunch of decisions. And sometimes the answer is not always clear, and it might just come down to Preferences. So a style guide could cover topics like tone and formality level. Are you casual? Are you formal
Lauren Schaefer 7:45
grammar and formatting guidelines most important to me, do you use the Oxford comma? I hope so.
Lauren Schaefer 7:52
The ideal reading level, I’ve heard from several people, you may not want to go above eighth grade reading level. Keep in mind, English may not be the first language of people who are reading your docs. So you want to keep things easy to read.
Lauren Schaefer 8:09
inclusive language guidelines and words to avoid. You don’t want to cause anyone harm or distract them from the information that you’re trying to convey. So use inclusive language.
Lauren Schaefer 8:21
How to talk about important terms and actions. Maybe there are particular verbs you use to describe actions the reader or the technology is taking
Lauren Schaefer 8:32
and what use cases or themes you want to use for examples. Perhaps you have a running theme throughout your Doc’s, like a pet shop example.
Lauren Schaefer 8:42
If your team already has a style guide, take the time to familiarize yourself with it and reference it when you have questions.
Lauren Schaefer 8:50
If your team does not yet have a style guide, you can start with a publicly available one like the Red Hat style guide. If you make a decision that differs from or enhances the style guide, you’ve chosen, document that decision and a place like a team wiki or a file in your code repo.
Lauren Schaefer 9:09
Now full disclosure I am a Grammarly employee, but I want to make you aware that there are tools like Grammarly that will provide inline suggestions based on your own style guide. It’s like the difference between having code formatting rules in a wiki page and having a linter as part of your CI CD process that enforces those code formatting guidelines. So, best practice number five, read the style guide or select one.
Lauren Schaefer 9:38
Moving right along Best practice number six build code samples.
Lauren Schaefer 9:44
A clear code sample is worth 1000 words. Developers commonly skim documentation looking for code samples. They’re hoping that they can copy and paste code directly into their application and that the code just works
Lauren Schaefer 10:00
So here’s some recommendations for building code samples.
Lauren Schaefer 10:04
Write just enough code to demonstrate the concept that you’re describing.
Lauren Schaefer 10:11
Ensure the code sample conforms to the best practices of the programming language being used.
Lauren Schaefer 10:18
Optimized for readability over code efficiency.
Lauren Schaefer 10:24
Note any prerequisites that are needed in order for the code to run. For example, note any imports that should be at the top of the file, or if the reader needs to install a specific version of something.
Lauren Schaefer 10:37
No note if the sample includes code that you do not recommend for production. So Best practice number six, build code samples.
Lauren Schaefer 10:47
Our final best practice today, review your work.
Lauren Schaefer 10:53
It’s almost certain that your first draft will have room for improvement. You might skip a key step leaving your readers feeling confused or frustrated. Or you might have grammar mistakes or wordy sentences that distract or confuse your readers. So get some feedback.
Lauren Schaefer 11:13
Similar to code reviews, documentation reviews, improve quality, and spread knowledge among team members. Create a documentation review process that makes sense for your project.
Lauren Schaefer 11:26
But no matter what, I strongly recommend that you do a self review. Waited at least a day after you finish the first draft before doing your self review so that you’re more likely to catch mistakes. Read through your documentation from top to bottom to ensure that it makes sense. If you’re writing a guide with steps, try the steps yourself in a fresh environment. Pretend like you’re a new user.
Lauren Schaefer 11:53
Use a tool to ensure that your writing is clear, polished, effective and free of mistakes. And step through any checklists that your reviewers will use so that you’re proactively catching anything before your reviewers do. This allows your reviewers to give you a higher quality review.
Lauren Schaefer 12:12
Now for public documentation, I recommend three layers of reviews. So start out with a self review. After that’s complete request a technical review. And after that’s complete request a copy review.
Lauren Schaefer 12:27
Now I love a review checklist to keep us consistent and ensure that nothing major gets skipped. So here are the checklists that we use. I’m not going to read through these now but feel free to grab a screenshot and use them in your review process. So Best practice number seven, review your work.
Lauren Schaefer 12:46
Alright, so let’s recap the seven best practices for writing documentation.
Lauren Schaefer 12:53
Read some of the docs.
Lauren Schaefer 12:56
Identify what needs to be documented.
Lauren Schaefer 12:59
Learn about your reader.
Lauren Schaefer 13:02
Right so your docs are skimmable.
Lauren Schaefer 13:05
Read the style guide or select one.
Lauren Schaefer 13:09
Build code samples.
Lauren Schaefer 13:11
And finally, review your work. I can’t wait to read what you write. Enjoy
