A Primer on Writing Good Documentation

JeffMatsonThumbnailThis 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

Documentation Words
photo credit: Variatie – Tekst(license)

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

Impact Image
photo credit: Eruption(license)

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

Documentation Art
photo credit: Space invader. Paris. Gare de lyon(license)

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.


13 responses to “A Primer on Writing Good Documentation”

  1. // Little is known about the documentation writers out there who shed their blood, sweat, and tears to ensure everything runs smoothly. //

    Well said!!

    PS: I recently changed my career to become a technical writer. As a WordPress fan (been using WordPress for more than 7 years), I would love to write some WP documentation if there are opportunities available. Any pointers?

    • If you’re interested in writing technical documentation, we can always use more help writing inline docs for WordPress core. If you’re interested in writing developer-facing documentation, the docs team is still writing and editing the first version of the official Theme Developer Handbook. The best place to start for either effort (or something else) is to join the #docs channel on the official WordPress Slack team. Visit https://make.wordpress.org/chat to get started.

      • Hi Drew,

        I tried to get started with the official WP documentation, but I didn’t quite get the process. I will give it another try.

        Do you participate there?

        • I’m the docs committer for WordPress core, so I guess you could say that I “participate” somewhat in writing inline documentation ;) As for the other stuff, I participate there too.

  2. When writing support documentation it might be a good idea to examine the bounce rates on specific pages. A high bounce rate may mean users are confused and are going elsewhere. A low bounce rate may mean users are sticking around and reading it (which is what you want).

    • I entirely agree to an extent. I think what you are referring to may be better attributed to time on page vs bounce rate.

      While bounce rate should always be improved upon, I have noticed in several years writing documentation for various high-traffic sites, that bounce rates are typically high within documentation and doesn’t entirely attribute to usefulness of the docs.

      Time on page, however, does indeed dramatically reflect the usefulness of docs.

  3. I don’t like to be that single critic but hey – it has to be said. Gravity Forms is great plugin but documentation is way far from being good. Recently I switched to GF from Ninja Forms and studied all GF docs. Then I had to open the code and see how it actually works. Then I’ve built a complete user frontend, membership and payment solution for community website, without using any extra plugins like GF + Custom Post Types etc. It’s kinda strange for me – most plugins that rock (ACF Pro, GF etc) suck in docs.

    • Gravity Forms does indeed need better docs, which is why they hired me. Being there for a bit over 2 months now, of course I can’t fix everything at once, but things are certainly improving.

    • I don’t remember how docs was before, anyway I like how it is now there. Its well structured, really nice designed.
      Not sure if its already changed or it will be changed, but I really enjoyed to searching there for my needs and found answers there.
      So if its already your job Jeff, thank you for great job.


Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

%d bloggers like this: