Product Documentation for WordPress Professionals

Product documentation is usually seen as inconsequential, that you can cut corners. It is not seen as something that can offer value to the client, or as something that could possibly affect key business areas such as revenue and marketing. Granted, as a WordPress professional you won’t need to write documentation in the same manner as Atlassian, or Cisco. Usually, when people think of “documentation” they conjure up images of thick, printed user guides, indexed alphabetically on a very large shelf that no one ever reads. 

But this has changed:

With the advent of Agile and DevOps, shipping software has become faster and the development cycle has also become more dynamic. And as a result, documentation now reflects the current state in the newest release, instead of being something static written on paper for ever. Documentation is integrated into the development cycle and is updated as frequently as software. 

Why should WordPress professionals care about product documentation?

Useful, up-to-date documentation not only does it make the life of your users easier, but it also adds a level of polish that becomes a marketing asset like no other. Conversely, poor documentation has a negative impact. You have probably experienced this yourself: You had a problem you were trying hard to find the solution for in the documentation and when you didn’t you ended up frustrated (and probably angry).  It only gets worse if you are paying for the product.

If you are working at a WordPress agency, delivering documentation across all areas of a project, from initial design to assets, will add a level of professionalism showing that:

1. You pay attention to detail.
2. You care about your client enough to go the extra mile.
3. You are transparent and confident about your design and technical project decisions.

Mike Puterbaugh, VP of Marketing at MindTouch wrote a Mashable article describing the 5 reasons your product documentation is a marketing asset. He concluded with the following:

It’s not a sexy undertaking, but it will earn you the respect of your peers, more effective company management and a more collaborative team. Because it’s not about this quarter or this year, but rather, it’s about affecting competitive advantage and long-term growth.

Now that we’ve established enough motivation, we will:

1. Explore the different types of product documentation that are relevant for WordPress.
2. Discuss the needs of each documentation type and offer actionable advice.
3. Offer some initial guidance on how you can plan and collaborate on product documentation. Particularly if you are working at a WordPress agency.

Types of WordPress product documentation

A WordPress product isn’t only about plugins and themes. In this section, we will also discuss online help, REST APIs, and a curious thing called microcontent.

WordPress plugins

WordPress plugin documentation needs to cater for two crowds: users and developers. The documentation needs of each are different, as is the writing style used. 

Users

The documentation needs of the users revolve mostly around troubleshooting and configuration. Add to this that you need to present your plugin in an attractive manner so as to get users to try it out. Every plugin has its own page in the WordPress plugin market. Do keep the following points in mind:

• Write a compelling and useful description that encourages download and use.
• Add annotated screenshots from your Dashboard plugin configuration page with descriptions.
• Put questions in the FAQ that are useful and not trite.
• Have an updated and well-written Changelog. Don’t add cryptic or terse notes there.

You should remember that when users are using the documentation, they are probably in a hurry and anxious to find a solution. Write clearly, simply and concise. Don’t make it harder for them than it already is.

Developers

Besides following best software practices  and  official PHP coding standards, you should focus your attention on the following areas:

plugin hooks

These do the work of modifying the behaviour of WordPress. Quite probably your WordPress plugin uses those. Since plugin hooks are an important part of the code, you should document how you use them and in what WordPress functions they are involved.

template tags

Template tags are another way for a WordPress Plugin to enhance functionality. Document the template tag functions that you’ve written. Include examples as to how other users or developers can use the tags on their WordPress site.

options

Options are a way to store particular pieces of information in a WordPress database. This is done via the add_option and get_options functions. In this case, document the parameters that you pass to these functions.

database

Plugins frequently read and write lots of different things from a database. Since these are fundamental operations, documenting them will greatly help other developers understand how your plugin works.

WordPress Themes

There are two different areas that you can create documentation for themes. The first is the source files. Commented CSS files are easier to understand and read than the ones without.  Use a tool such as css_doc to help you. This generates a JavaDoc style of documentation and it can be published:

The other area is Style guides. These documents describe how elements need to look and in what cases they need to be used. They enforce consistency and make collaboration easier as well. You can read Hubspot’s 20 stunning examples of brand style guides article as it contains lots of great examples.

Again, do not forget to consult the official WordPress CSS coding standards.

Documenting design elements in such detail also helps the onboarding of new employees if you are a WordPress agency. Style guides can be used as tutorials or referencing material for new and past client work.

Online Help

Since online help aims at solving a particular user problem, starting with a list of common tasks and problems is the way to go. Although the list at first won’t be exhaustive, take the time to produce as many concrete items as you can. The idea is to write an online help file for each of these tasks and problems, and hyperlink them to related information. You can create user journeys to map out the different paths a user can take and do within your application. Diving into support emails to notice common questions and problematic areas is a good way to keep your knowledge base up to date and useful.

Barry J. Rosenberg, author of  Spring into Technical Writing offers the following pieces of advice in order to write good help files:

Keep each help file as brief as possible. Prefer numbered lists to bulleted lists. Don’t digress, don’t footnote, and don’t wanter. Keep each help file focused on a single discrete task.

Microcontent

Microcontent has two definitions: the first being that is content like headlines and sections that users skim, in order to get the gist of a particular article. The second is small bits of content that can stand on their own and are used to enhance user experience. One particular excellent example we have in mind is Slack’s “several people are typing..” bit.  (although Slack is full of excellently written microcontent).

That bit gets triggered when more than 3 people are simultaneously typing in the same channel. Instead of just printing a list of people that currently type, Slack takes this boring piece of information and adds some fun to it. The discussion is starting to get really hot, and it shows. It is an excellent example of how product documentation (application messages are part of that, no?) make people talk about you (and create hilarious memes like the above).

REST API

Documenting REST APIs is a separate art in and of itself. As with all technical writing, you should aim for conciseness, clarity, and simplicity in definitions. Since REST APIs have their own format and intricacies, you could do no worse than studying the excellent guide for documenting APIs by Tom Johnson on his I’d Rather Be Writing blog.

Collaborating and planning documentation

Ultimately, documentation should be part of product design. As such, you should approach it as having an extra pipeline in your software cycle. This means using software repositories to store the most current documentation version, using bug/issue trackers to monitor tasks and problems, include documentation project planning to your roadmap, and last but not least, collaborate with other people. A rough outline of how to begin could be the following:

1. Record everything that the user would want to know, as well as areas that you will need to write text for.
2. Once you have everything, group them in categories and form document titles.
3. Write a spec for each document detailing things such as title, description, target audience, media (what form will the document have), length, how much time it will take, etc.
4. Add the estimates from the documentation specs to your project planning.

Since product documentation cuts across all areas, it is almost certain that you will need to work with different people within the organization. It is a good idea to sit down and agree on some sort of process of how all of this will go. As in every project, you should identify the stakeholders who will provide technical assistance, as well as those who will review and edit changes.

There should be different stages of the process. These should map out where information is gathered, when the document is written, when it is ready for literary proof-reading, for technical comments, publishing and such. Emphasise on the difference between literary, technical, and content-related comments. For example, it’s not really useful when you ask a team leader to comment on your document and instead of technically related information, you get cries for grammar and punctuation.

Closing

Product documentation is an asset that pays off in the long-term. It gives value to your client. It might even be so good, like Stripe’s API documentation for example, that people rave about it in forums. This builds engagement and advertises your brand and your product in a natural and powerful way. When coupled with creative microcontent it achieves what Mike Puterbaugh means when he says that product documentation is “marketing’s secret weapon”.