Tips for writing great documentation

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:

1. 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).
2. Use active voice and actionable content. Active voice keeps your readers focused on themselves and what they should do.
3. Share pseudocode instead of real examples. When you do this, you force the reader to synthesize your content and really understand it.
4. Identify and isolate atomic units and let the links proliferate. Write crisp topics and share them for others to build with and on.
5. Make it fun. It's always easier to read something you enjoy reading.
6. Use highlights. Do what it takes to feature the important points (or draw attention away)
7. Outline and test. Tell the story with your headlines and get feedback on what you're writing.
8. 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.
9. Experiment. Try fresh approaches or try something tangental. It helps you grow as a communicator.
10. Keep reference information short and to the point. "Don't be afraid to use the plainest language possible."
11. 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!
12. 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.