One of my favorite things to do is write documentation. I love organizing information in a way that captures my understanding of a system or process, and the act of writing documentation is the best way that I’ve learned to synthesize information for others as well as my future self.
I’ve seen great documentation. I’ve also seen documentation that looks like the author’s scratch notes after a long day at work. Good documentation leaves me feeling comfortable and confident in my newfound knowledge; other documentation leaves me scratching my head, and I often have more questions than when I started.
Here are a few things that I notice in my own writing that help to keep my documents accessible to as many people as possible.
1. Get to the point : )
Keep things short and don't say more than you have to! Readers have a short attention span and will oftentimes miss key information if it's surrounded by superfluous text. Say things using plain language that is understandable to your readers, and simplify sentence structures to be clear, unambiguous, and with active and positive language.
Define acronyms and abbreviations the first time you use them, and look for ways to use common language instead.
2. One idea per paragraph.
Focus on a single point that you want readers to take away in each block of text. Our brains like to take shortcuts and skim larger blocks of text, making it harder for readers to absorb information.
For people that like to write in a stream-of-consciousness style by default, one of the first things I always recommend for them is to break up their paragraphs.
Yes, paragraphs with a single sentence are still paragraphs. Do not be afraid of the Enter key!
3. Leverage formatting.
Depending on the documentation tool that you're using, you can use lists, text highlights, callout blocks, expanding sections, section dividers, tables, and typographic and color hierarchy to make it easier (and more interesting) for readers to visually segment and prioritize information.
Some information may be secondary to the main points, and can be deprioritized or “opted into” for readers that are looking for more detail.
This is a very basic example that showcases how much easier it can be to read information that is presented in the right way (yes, even when the styling is b o r i n g):
4. Provide a table of contents / navigation.
For longer pages, give readers an easy-to-access overview of the main sections of your page, whether that’s in a table of contents or some sort of navigation menu. This allows readers to orient themselves before reading the rest of the page and at any point in time as they are scrolling or clicking around.
It also allows them to skim the (hopefully-useful) headings so they can more easily decide if the page has what they’re looking for.
5. Break down large pages.
Similar to breaking down paragraphs, breaking down large pages allows us to organize information into higher-level concepts and reduces the amount of information that a reader has to absorb or navigate all at once. Provide a high-level overview of concepts and direct readers towards more detailed pages that they can drill into depending on their needs and what they're looking for.
6. Know your audience.
Some people will need a general domain overview to orient themselves within a project or organization; some may be looking for historical context on what's happened and why it happened; and others may just need hands-on details of how to get something done. Knowing why you're writing documentation will allow you hone your message instead of diluting it.
7. Provide information in different formats.
Some people are visual learners and understand best by pairing information with a well-organized diagram; others work best with reading materials, or by watching video walkthroughs and tutorials. If you're able to organization information into several different formats, you'll be better equipped to suit a wide variety of audiences.
8. Tell a story and make it a conversation.
The best way to capture a reader’s attention and make them care about what you’re writing is to tell a good story, bring them on a journey, and anticipate how they’re feeling at any given point. Write like you’re telling a story to one of your friends.
Think about the overall structure of your documentation and how a reader is going to experience reading through it — do they have enough context about what they’re reading and the audience it’s written for? Does the information flow smoothly from one idea to the next? What questions can you imagine them asking as they read through your page, and what other pages or references are related or supportive that you can provide?
Designing for reading
One of my favorite parts of the plainlanguage.gov guidance comes from their “Design for reading” page:
We want our writing to help people get information, comply with requirements, and apply for benefits with the least possible burden. Dense, cluttered writing deters people from taking the time to read.We’ve heard from many readers that when they get dense, uninviting letters or notices from the government, they often put it in the “read later” pile, even though they know they should read it right away.
Imagine yourself reading your documentation for the first time without context. Does it make you feel comforted and excited to read? Or does it make you uneasy, like you’d rather be doing something else?
If you don’t want to read your document, others won’t either. Give us something worth reading!
Â