I recently read a great article by Taylor Singletary who's been writing documentation for customer facing products that almost all of us use: LinkedIn, Twitter, and Slack. If you ask him, he says he works in "developer relations." He wrote up the list of things he does to create great, usable, customer-facing documentation:
- Always tell stories. Your reader should be the star of your story (even if it's about implementing an API or handling an error condition).
- Use active voice and actionable content. Active voice keeps your readers focused on themselves and what they should do.
- Share pseudocode instead of real examples. When you do this, you force the reader to synthesize your content and really understand it.
- Identify and isolate atomic units and let the links proliferate. Write crisp topics and share them for others to build with and on.
- Make it fun. It's always easier to read something you enjoy reading.
- Use highlights. Do what it takes to feature the important points (or draw attention away)
- Outline and test. Tell the story with your headlines and get feedback on what you're writing.
- Routinely revise old content. Make sure new concepts are threaded through old content and don't be afraid to try a couple of different approaches.
- Experiment. Try fresh approaches or try something tangental. It helps you grow as a communicator.
- Keep reference information short and to the point. "Don't be afraid to use the plainest language possible."
- Use FAQs. FAQs give you a way to anticipate reader questions and point everyone to the same answer. Put one in a margin or a pull out!
- Monitor the effectiveness of your documentation. Track how often the same questions or problems come in, figure out why it's happening, and fix it!
It was a fun read. I found that the way he described the all-too familiar points really drove the point home in a relatable, enjoyable, and memorable way. I encourage you to read the whole thing and maybe join me in reading some Twitter or LinkedIn documentation.
best practices, topic based writing