When I joined Grammarly as a developer advocate, my first task was to write documentation for how to use the Grammarly Text Editor SDK with desktop apps built on Electron. While I had experience writing tutorials, articles, and READMEs, I had never written official product documentation.
I was in way over my head. The blank page problem was way too real. I was experienced in writing tutorials for specific examples, but I struggled with figuring out how to describe steps and concepts in a way that was broadly applicable to a variety of use cases. I went back and forth in my mind about how much detail to provide.
I pushed through the discomfort and, with the help of some quality reviewers, published my first piece of official product documentation. While I haven’t yet come to love writing documentation, I have gotten better at it over time.
If you’re a developer or a software engineer, chances are good that you’ve written documentation previously or will need to in the future. Perhaps you’re writing official documentation for your users or something more informal, like internal documentation for your teammates or a README.
In this article, I’ll share ten best practices for writing documentation that your readers will enjoy. With every best practice, I’ll give a concrete example related to my experience. By the end of the article, you’ll be ready to write documentation and maybe, possibly, even excited about the prospect of doing so.
Jump to:
2 Identify what needs to be documented
4 Write so your documentation is skimmable
5 Read the style guide (or select one)
8 Determine your tolerance for outdated documentation
1 Read (some of) the docs 👀
If you’re adding on to an existing set of documentation, start 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, a getting started guide, and something similar to what you will be writing.
Look for patterns in 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’ll want to match these aspects in your new documentation. In many cases, you’ll want to aim for your documentation set being so cohesive that it will seem like it was written by one person.
If you find something that is confusing or that could be improved while you’re reading, take a note or open a ticket. Don’t get sidetracked into fixing everything right away.
In my case, I started by reading the Text Editor SDK overview page as well as similar pages for how to use the SDK with JavaScript, React, and Vue. I created a spreadsheet where I noted any areas for improvement, including places where I became confused or terms that were used inconsistently.
If you’re writing a new set of documentation and don’t have the luxury of reading existing docs, do a light read of the documentation for similar projects. Note what you like and what you don’t like. This will give you inspiration as you start writing.
2 Identify what needs to be documented 🔍
The next thing you need to do is identify what you need to document. Go beyond just the topic, and note the details that you need to document. Consider points like:
- What concepts do your readers need to understand? Do you need to explain those concepts or link to other resources that explain them?
- What prerequisites will your readers need to complete before beginning?
- What steps will your readers need to take?
- What will the reader learn or accomplish after reading your documentation?
- What versions of the software does this documentation apply to? If you’re documenting how two pieces of technology work together, what versions of each are supported?
If you’re not already an expert on the details, dig in to learn them. Perhaps you do online research, perhaps you try the steps yourself, perhaps you ask an expert questions, or perhaps you do a combination of all three. Keep notes about things that confuse you or where you get stuck. Be sure to detail the steps you’re taking as a 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 steps in a fresh environment; it’s easy to forget that you previously installed something months ago when you tried it for the first time yourself.
My task was to document how developers can use the Grammarly Text Editor SDK in Electron apps. I met with members of our engineering team for a video call. They walked me through the steps of adding Grammarly suggestions to an Electron app. They also showed me how to set up connected accounts for an Electron app, because the steps were different from the steps that were already documented for web apps. I asked the engineers tons of questions and took a lot of notes. After the call, I tried adding Grammarly suggestions to an Electron app on my own, detailing the steps I was taking. Admittedly, I got stuck a few times, and messaged the engineers on Slack to get clarification. By the end, I had a detailed list of steps for the basic getting started flow as well as setting up connected accounts.
3 Learn about your reader 🧑💻
If you’re lucky, someone has already identified your reader for you. If you’re writing external-facing documentation, perhaps your team has already created detailed personas. If you’re writing internal documentation for your team, you know your readers personally.
Try to answer the following questions about your reader:
- What is your reader trying to accomplish?
- What do they already know about the topic?
- What concepts and terms will be new to them?
- How does your reader want to find the information they need?
We didn’t have a detailed persona I could work from—we were still collecting feedback from our early beta launch of the SDK, and this feature was due to be released the following week. I took my best guess about our reader:
- They want to add communication assistance to their existing Electron app.
- They are already familiar with building Electron apps.
- They don’t know anything about the Text Editor SDK.
- They want clear written steps for getting started with the SDK, they want to skim the documentation to find what versions of Electron we support, and they want a working code example in GitHub.
4 Write so your documentation is skimmable 📝
People rarely read the entire set of documentation from start to finish. Instead, they’ll find a page that they think will have the information they need and then skim it—starting first with the headers and then drilling down into any sections that look relevant.
Here are some tips for writing documentation that’s easy to skim:
- Use descriptive headers that allow your reader to quickly determine if a section will provide the information they are looking for.
- Write in short paragraphs focused on a single idea.
- Use bulleted lists to share groups of information.
- Use numbered lists to share sequential or ordered information.
5 Read the style guide (or select one) 💅
Just like a development team creates code formatting guidelines, your team can create a style guide for your documentation. A style guide is a document that provides rules and guidelines for consistent writing. When you write documentation, you need to make a number of decisions where the answer isn’t always clear and might come down to preferences. A style guide could cover topics like:
- Tone and formality level
- Grammar and formatting guidelines
- The ideal reading level
- Inclusive language guidelines and words to avoid
- How to talk about important terms and actions
- What use cases or themes to use for examples
A style guide provides many benefits beyond just consistency. It allows you to transfer team knowledge to new teammates and provides guidelines for items that could otherwise become irritating and time-consuming if revisited for every piece of new or updated documentation.
If your team already has a style guide, take the time to familiarize yourself with it and reference it when you have questions. If your team doesn’t yet have a style guide, you can start with a publicly available one. Here are some examples:
- The Apple Style Guide
- The Red Hat Supplementary Style Guide for Product Documentation
- The Twilio Writing Style Guide
If you make a style guide decision that differs from or enhances the style guide you’ve chosen, document the decision in a place like a team wiki or a file in your code repo.
If you are using Grammarly Business, you can codify your style guide in Grammarly using the style guide feature. The style guide feature allows you to create custom suggestions for your team. I’ve found I’m much more likely to follow a style guide when I get inline suggestions than if I need to remember to apply the guidelines myself.
Internally, we have an extensive style guide at Grammarly that we’ve codified using the Grammarly style guide feature. This means that whenever I use Grammarly to analyze my writing, I get inline suggestions customized to our company’s preferred tone and brand voice.
6 Build code samples 🧑💻
A clear code sample can be worth 1,000 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.
Here are some recommendations for building code samples:
- Write just enough code to demonstrate the concept you’re describing in the documentation.
- Ensure the code sample conforms to the best practices of the programming language being used.
- Optimize for readability over code efficiency.
- 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 a specific version of something installed).
- Note if the sample includes code that you do not recommend for production use cases.
I personally love when product documentation includes a way for me to try the code in an interactive environment. The setup is faster for me, and I’m much less likely to run into unexpected errors caused by differences in my local environment.
Many of the pages in the Grammarly for Developers documentation include embedded code snippets as well as links to CodeSandbox environments. Each CodeSandbox environment runs a code example that we store in the Grammarly for Developers GitHub repository.
For example, the documentation page on the Grammarly Text Editor SDK for JavaScript contains several short code snippets, so readers can skim for the relevant code they need. The page also include a link to an interactive example on CodeSandbox. The interactive example allows readers to see both the code for a complete, working example as well as a preview of the rendered example.
7 Review your work ✅
It’s almost certain that your first draft will have room for improvement. You might skip a key step, leaving your readers confused and frustrated. Or you might have grammar mistakes or wordy sentences that distract or confuse your readers.
Similar to code reviews, documentation reviews improve quality and spread knowledge across team members. Create a documentation review process that makes sense for your project. If you’re writing internal documentation for something like setting up your development environment, perhaps you post it in a team wiki and ask the next person who tries it to give you feedback or update it themselves. If you’re writing public documentation, you’ll likely want a more robust review process.
Regardless of whether you later ask someone to review your documentation, I strongly recommend you review the documentation yourself. Wait at least a day after you finish the first draft before doing your self-review so that you are more likely to catch mistakes. Here are some tasks you’ll likely want to complete as part of your self-review:
- Read through your documentation from top to bottom to ensure it makes sense.
- If you’re writing a guide with steps, try the steps yourself in a fresh environment.
- Use a communication assistant like Grammarly to ensure your writing is clear, polished, and effective.
- Step through any checklists 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.
I love a review checklist to keep reviews consistent and ensure nothing major gets skipped. Our Grammarly for Developers documentation has three levels of reviews: a self-review, a technical review, and a copy review. I’ll share our review checklists that you can modify and use:
Technical review checklist
- The documentation accurately describes how to use and/or configure the functionality.
- The documentation is complete (covers all relevant aspects of the functionality).
- The documentation includes correct version requirements.
- The documentation contains all relevant links.
- The code samples follow the given language’s best practices.
- The documentation uses technical terms correctly.
- The code samples work.
- The steps work from top to bottom in a clean development environment.
Copy review checklist
- All images have appropriate alternate text.
- The documentation uses terms correctly and consistently.
- The links in the documentation work as expected.
- The documentation organization and flow are logical.
- The documentation is grammatically correct.
- The documentation follows the style guide.
8
Determine your tolerance for outdated
documentation ⚖️
Whatever you’re documenting is likely to change, and your documentation will probably become outdated or inaccurate at some point. Highly motivated readers might push through broken documentation and figure it out themselves, but unmotivated readers might simply give up when something doesn’t work.
Consider your readers’ expectations and the time you have to devote to building and maintaining the documentation. In some cases, you might have a high tolerance for outdated documentation; you might ask your readers to update the documentation themselves or directly chat with you if they find something no longer works. In other cases, you might have an extremely low tolerance for outdated documentation; a broken getting started guide could have a massively negative impact on your users.
Determine your tolerance for outdated documentation and build a process accordingly. Here are some examples:
- Ask readers to contact you directly if they need help following the documentation
- Provide contribution guidelines so readers can make updates to the documentation themselves
- Add a survey widget to the documentation that allows readers to report issues
- Provide a discussion forum where readers can ask questions
- Include documentation updates in your merge checklist
- Write automated tests for your documentation steps and code samples, so you’ll know right away if a code change results in outdated documentation
We use several of these approaches on the Grammarly for Developers team.
All of the pages in the Grammarly for Developers documentation contain a rating widget. If a user provides a low rating, they have the option of including a comment on how the page can be improved.
We also allow readers to report issues and ask questions in the Grammarly for Developers repository on GitHub.
Our release process requires the related documentation to be included with feature updates and releases. Our developer education team attends the engineering team’s daily standups, so they are kept in the loop on what is being developed and changing. They work on the documentation throughout the sprint, ideally culminating in code and documentation that is completed at the same time.
9 Future-proof your visuals 😎
As I mentioned earlier, whatever you’re documenting is likely to change. So how can you future-proof your visuals and minimize the maintenance cost?
One of the easiest things you can do is minimize the number of screenshots and videos. I know, I know—visuals can be super helpful. However, user interfaces frequently change, and the cost of updating screenshots and animations is higher than the cost of updating plain text. The cost of updating videos is even higher.
When possible, use abstract illustrations that are not tied directly to the product UI. For example, we display the animation below on our User Feedback page. It illustrates the concept of user feedback but doesn’t show the menu options that lead to the user feedback survey. This animation will remain relevant even if our menus change.
Sometimes, a screenshot is the best way to enhance your text description. In those cases, minimize the amount of the user interface that is included in the screenshot.
For example, when writing about the Monitoring section of the Dashboard, I might be tempted to include a screenshot of the entire Grammarly Developer Hub UI.
Instead, I could crop the screenshot to only show the Monitoring section. This means that if any of the navigation bars change, my screenshot is still accurate.
10 Document decisions ⌨️
As you’re writing documentation, you’re likely going to find yourself waffling about something: maybe it’s a term, maybe it’s the verb you use to describe an action the user is taking, or maybe it’s how much of the screen to include in a screenshot. You might waffle by yourself, or you might pull in a teammate to help you make the decision.
Whenever you make a decision, write it down. Put it in your style guide.
Consistency in documentation is key. Once you pick a word for a concept, use that same word every time. Synonyms are not your friend. If you use two different but similar words, readers will wonder if you are referring to the same thing.
I recommend creating a glossary of key terms and definitions. Whenever you introduce a new concept, drop it in your glossary.
The glossary could live publicly in your documentation or privately in your style guide. I’ve found that selecting a term is much easier than creating a perfectly wordsmithed definition. If you know that you’ll be tempted to debate and perfect the definition before putting it somewhere publicly, keep an internal glossary with working, messy definitions. Perfecting the definition isn’t your top priority right now. The important thing is to pick a term and use it consistently.
In the early days of creating our Grammarly for Developers documentation, we had to make a lot of decisions. Often this involved discussions with our engineering team as well as the broader Writing and Content Design team at Grammarly. Here are some examples of decisions we documented:
- When to use “Grammarly Text Editor SDK” vs “we” as the subject of the sentence
- How to format inline code snippets
- What to name specific terms and concepts (eventually, we used the names we documented here as the basis for an official glossary in our docs)
Summary
In this article, I shared 10 best practices for writing documentation:
2 Identify what needs to be documented
4 Write so your documentation is skimmable
5 Read the style guide (or select one)
8 Determine your tolerance for outdated documentation
Like any skill, writing documentation is difficult at first and becomes easier the more you practice. Don’t fret if you find yourself staring at the blank page, wondering how to begin. Find a place to start—it doesn’t need to be the beginning—and jot down all of your thoughts. The first draft doesn’t need to be anywhere close to perfect.
I’d love to hear from you! Where are you getting stuck writing documentation? What tips can you share? Start a discussion in the Grammarly for Developers repo on GitHub.
