A Primer on Writing Good Documentation

This post was contributed by guest author Jeff Matson. Jeff is the head of documentation for GravityForms. He is the creator of the Heartbeat Control WordPress plugin and is a fan of the 90s.

---

Often times, documentation is the most underrated piece of the development process. When we look at rockstars in the WordPress community, we typically look at developers, designers, and marketers. Little is known about the documentation writers out there who shed their blood, sweat, and tears to ensure everything runs smoothly.

This post is about those who day in, and day out stare at endless lines of code to decipher what the developer was thinking, and the true meaning behind the code that exists.

Good Documentation is More Than Words

Good documentation writers provide more than an instruction manual, they provide an experience. I have known excellent documenters, coached beginners, and the largest difference between them is understanding the brain of those reading it. Just like a novel, documentation has a flow that keeps the reader interested and ingesting more information than they realize.

Quality documentation targets the users that are most likely to read it. It also provides a point of reference for those who are more unlikely to read it. For example, if documenting a particular hook, it’s typically assumed that a developer will be reading it, but what about those who have little development experience?

A good documentation writer will provide a point of reference for those who need more of a push in the right direction, without the need to contact support to spell it out for them.

Documentation Has a Larger Impact Than You Think

Most simply ignore documentation, pushing it off into the endless abyss until they can’t take it anymore. I’m guilty of the same thing in some cases. What those people don’t realize, is that every moment their plugin or theme is left undocumented, user experience suffers.

Let’s take a look at your most common support ticket. If you better documented that issue, would those tickets go away entirely? Probably not. Would you get fewer tickets regarding the issue as well as increase you or your support agent’s productivity? I guarantee it. I think we could all use fewer support tickets.

As I mentioned previously, documentation makes a dramatic impact on user experience. If the user is able to locate the information easily and efficiently, they have saved their own time as well as yours. The average world life expectancy is 66.57 years and your users would rather be doing something else with their lives than fiddling around with poorly written documentation.

If a customer sees that you have put quite a bit of time and effort into your documentation, they will, whether consciously or not, better appreciate you. Good documentation shows you care about them after the initial sale.

Have you ever been left high and dry after spending hard-earned money and soon regretted the purchase? I think we all have. With proper documentation, you can avoid passing that feeling off to your customers.

How Can You Write Better Documentation?

The first step is to stop avoiding it. Once you’re good at it, writing documentation is more of a pleasurable experience than you think. In fact, it will become second nature. Just like everything else in the world, practice makes perfect.

One of the first steps you want to take when deciding to take your documentation to the next level is to determine your pain points. What are you being contacted about? If you start blindly writing about things, you may find that what you’re writing about isn’t making as much of an impact you would like it to.

One of the best techniques I have discovered is to track the number of tickets that are documented vs. those that are not, and break those that are not into categories. This way, you can better target your pain points, and revise the parts that may not be as helpful as they should be.

After you have determined what documentation you should write, you should determine your target audience, and break it down into developers, users, and power users. This helps you cater to that particular audience. We’ll go over how to target those users a bit later.

Next, you want to break down the document. For developers, you’ll want to break it down into raw information (accepted arguments, return values, etc.), specific examples and use-cases. For users, the best course of action is a walkthrough. Every step they will need to take, regardless of how trivial it may seem, is critical.

Spell it out to them every step of the way. Documenting for power users is very similar to a user scenario, but more structured and scannable. Be clear, but allow them to easily jump to where they need to go without reading the previous step first.

The Art of Writing Better Documentation

When it comes to the art of writing your documentation, write in a way that best targets your audience, but also use simple language that you know they will understand. One of the best reasons for this is due to translations. While Google translate does an excellent job, it’s much easier to translate the simple vocabulary of a 5th grader than that contained within a post-grad thesis.

Within your content, don’t be afraid to link to relevant content. This will allow you to avoid repeating yourself through multiple documents, as well as allow the reader to back-track if they need more information about a particular subject. After all, your main goals are to make the user happy, and save yourself time.

The documentation process doesn’t stop after you press the publish button. Go back and revise every document as needed. Almost immediately after the document is published, go back and see if the support tickets you tracked have declined, and traffic to that particular article has increased. Usually, if you’re getting more traffic to an article, it’s helping. If you’re getting more traffic but the same number of support tickets, you may want to look into that article to see why.

What We Have Learned

First, I hope that after making it this far, you have a better appreciation for those in the trenches writing the documentation that most of us take for granted. It truly is an art form that many of us who write documentation for a living truly enjoy and put many, many hours into.

I also hope that you come away from this article thinking more about your existing documentation and how it can be improved. Proper documentation can be extremely rewarding and once in practice, can actually be quite fun to write.

Document early, document often. A great product is more than great code, it’s also beautifully documented.