Writing great documentation
Over the past eight years, I’ve enjoyed writing documentation, supporting developers, and stoking platform potentiality for LinkedIn, Twitter, Clever, and most recently, Slack.
I’m always learning from the amazing people I work with and from the talented programmers & creative partnerships that sprout from these evolving ecosystems. Even so, those of us in developer relations largely have to make it up as we go along. We make mistakes and we make them again. Occasionally, we even get something right.
Here’s how I help manage the stark blank page or wrangle a labyrinthine collection of text.
Always tell stories
Readers are most engaged when they star in the story you’re telling. Great writers leverage narrative arcs to keep audiences within their world long after their eyes have left the page.
Stories typically have a beginning, a middle, and an end. Somewhere between the middle and the end, there’s a satisfying climax that sheds light on everything that came before and leaves a lasting impression that colors the reader’s future.
You want your documentation to do that, to make your reader the hero of a story you’re telling, even if it’s about implementing a new API or handling an obscure error condition.
Active voice and actionable content
Using active voice throughout documentation not only reduces the effort to parse your text, but also provides your readers with the illusion of sitting in the driver seat of your project, honking at your clever bumper stickers and following your sign posts to places and experiences they’ll conjure along the way.
Active voice is focused on the actor and their actions. The subject of your sentences may be the developer, their application, and the specifics of the named things in your service like functions, API methods, or fancily named product features. The actions are what they should do with those things.
- Active: “Use `authorize` to exchange the code for a token” or “Exchange codes for tokens using `authorize.`”
- Passive: “The code is exchanged for a token using `authorize`.”
Of course, you’ll still use the passive voice. Not everything has agency. And sometimes the heart wants the phrasing that the heart wants.
Your content should also be actionable, filled with examples and exercises.
If understanding your material is paramount, avoid sharing specific code samples and use pseudo-code instead. That way your reader must synthesize your content to work with it.
It should be easy to get started but your content should be the key to mastery.
Your documentation should provide inline tools as applicable. Something tangible should inspire readers to go the extra mile to marry your product, service, or solution with their own project.
But be wary of providing out of the box solutions that over-abstract your platform. Technical support becomes more difficult the further removed developers are from the nuts and bolts of your API.
Atomic linking
Build a web of coherence and meaning with the building blocks of atomic content, logically linked together.
When I’m working on new documentation or revising something older, I’m always looking for more documentation to write. A single document is just part of a greater whole, and often the other pieces of that grand narrative are missing.
Every topic doesn’t warrant a dedicated document, but at the very least, you should write something crisp and throw it in a FAQ and give everyone something they can freak to and link to.
By identifying and isolating the core tenets of your subject, you can reinforce these pillars by prolifically inter-linking whenever discussing higher-level topics.
Still, don’t be afraid to repeat yourself here and there, or to link to the same topic within a piece of documentation multiple times.
Make it fun
That’s right, documentation should be fun. You can make anything sound fun using the right language, even hard things, even terrible things. Making things fun is where style inhabits the words you’re writing and what separates your content from uninspired dry, technical writing.
Making it fun means you can break rules, too, and breaking rules is as fun for your readers as it is for you. Telling a story is one way to help make it fun, but latch on to anything appropriate for your brand and audience that amps up the fun factor or fortifies your fun factory. Like little lathes of allusive alliteration.
Highlights for the children
See up there how I bolded “documentation should be fun?” I did that to highlight that content amidst a whole paragraph someone might have had to read to understand my full point.
Developers won’t read everything you write. They’ll miss many of your warnings, tips, and park benches.
If it’s important, highlight it. Your reader still might not read it, but they’ll be back one day and you’ll be ready.
Break content up with whitespace and bolds and italics and bigger, more fUNKy fonts — whatever you need to do to feature the most salient points of your content without being obnoxious.
Many different kinds of learners are out there and some just want to skim and won’t read anything they didn’t catch the first time.
Sometimes bolding isn’t enough and you want to break content out!
I put boxes around important factoids and use reverse color schemes to almost garishly get a point across. This is especially useful if you want to redirect attention from the current document to a related topic, or call out something particularly onerous... Or draw attention away from something odious.
Some concepts deserve mascots or icons and those should follow those concepts wherever in your documentation they may roam.
You probably aren’t working from an explicit style guide, so just make it up as you go along and re-use your best ideas as appropriate.
Starting new documentation projects
Is the new thing to be documented really a new thing or a part of something that already exists? Does it expand something small into something big enough of a deal to be its own thing? Does its very existence require change across all of your documentation or can it sit like a pebble thrown in a pool but making no waves?
Test first
Have you actually tested what you’re about to write about? If not, slow down! Go and test it and explore. It might not even be ready to document yet. If it isn’t testable, make it testable. Knock on doors, break down walls, throw some tables.
You should speak from a position of experience and expertise and it’s up to you to make that happen before an API or project is put in developer hands.
Then Outline (and keep on testing)
Throw some header tags down, don’t worry too much about whether they’ll be h1s or h2s or h3s, just get some headlines down that will help guide you through what you’re writing.
Tell your story with the headlines.
Identify the audience. Identify the purpose of the document and tell the audience that. By the time you write the conclusion, re-affirm that you’ve done what you set out to do and if you haven’t, either edit until you have, or recalibrate your document to what you actually did. Or start over!
Product feedback loop
As you test, outline, and author you will likely develop opinions about the software you’re working with. Maybe it’s too late to fix everything, but it’s never too late for your experience to illuminate limitation awareness and eliminate ambiguity, both internal and external.
Revising old content
No one can win against kipple, except temporarily and maybe in one spot… But eventually I’ll die or go away, and then the kipple will again take over. It’s a universal principle operating throughout the universe; the entire universe is moving toward a final state of total, absolute kippleization.
— Philip K. Dick, Do Androids Dream of Electric Sheep?
Old content becomes moldy and decrepit — even after beginning life as something inarguably great.
Routinely fix documentation bugs and stale concepts. While reading documentation, keep a log of the bugs you want to fix later, or just repair on the spot. Documentation is often as much for you and your team as it is for external developers.
Make time to ensure that new concepts are well-threaded throughout old artifacts — most platforms, even if not explicitly hypertextual, are very inter-connected!
Don’t be afraid to get rid of a page, passage, or approach that isn’t working. Kill your darlings, but wrap them in plastic bags and file them away for later. You may find them revivified and quite poignant one day.
Green fields and blue skies
Writing new documentation is an opportunity to “make it new” and explore fresh approaches and oblique strategies. Change your process, collaborate in ways you haven’t before, or take inspiration from something only tangentially related to your topic. It doesn’t matter if you won’t ultimately use your experiments.
Maybe your developer portal’s current structure isn’t right for what you want to author. Maybe you should actually write a newsletter, or a blog post, or a macramé tribute to your favorite API method.
Don’t squander these opportunities. This is where you’ll grow most as a writer, an educator, an editor, and a student.
Resource documentation
Great resource documentation should be short and to the point.
Pertinent details should always be discoverable at glance and a stone’s throw from paragraphs of text.
Use multi-column lay outs, consistent labeling, and don’t be afraid to just use the plainest language possible.
I’m frequently inspired by nutritional labels on cereal boxes.
FAQs
When you don’t have time to write a whole doc about something, write a FAQ.
Just formulate a question and then answer it and put it in your FAQ. It doesn’t matter if it’s frequently or ever asked. It’s like stand up comedy and you’re in charge of the setup, punchline, and tag.
FAQs are your secret weapon. Use them in sidebars, use them in pull outs, use them in macros and tweets.
Anticipate the different ways a question could be asked and route all the variants to the same canonical answer.
Finally
Listen to and observe your developers. They won’t always come right out and tell you what’s missing or what’s wrong or what could be clearer. It’s your job to intuit this by noticing common pitfalls, gross misunderstandings, and uninspired integrations.
Monitor the effectiveness of your documentation by tracking how often the same questions or problems arise. Revise and repeat.
Keep making the same old mistakes until you learn from them or find they weren’t mistakes after all.
Great documentation can make your developer support team more efficient, focused on your most important customers and most challenging & complex problems. Strong documentation filters out the noise, leaving you and your organization with an inspiring signal.
You’re the narrator, the teacher, the student and your classroom extends well beyond your text.
