Writing Online Docs

Writing online documentation is a craft that takes experience and critical feedback. Being able to make technical things clear and understandable in a tone that is empowering for the reader can be challenging.

This article walks through how we approach writing online documentation for our products.

Goals for All Documentation Articles

There are several important goals for every documentation article that we write.

1. Provide detail for all features of the product
2. Anticipate and answer any questions the reader might have related to the feature in question
3. Provide context to how this feature relates to other features of the product or add-ons
4. Expand the content of our website to further encourage search engines to make our website the authority on all technical matters related to the product

Documentation Voice

1. Docs do not use first person language such as “our plugin” or “our team.”
2. Docs use the same tone as support tickets, that of a wise friend.
3. Docs are designed to be skimmable.

Composing Docs

All our docs are custom post types built specifically for online documentation purposes. Documentation is a major source of content that greatly improves the search index for our website. Hosting our documentation on our website also ensures that we can build the docs in any way we see fit.

Summary

The Summary is a quick overview of what the reader should expect to learn from reading this doc. In just 1-2 sentences, the reader should know quickly whether they will find the answer to their question in this doc or not.

The Summary is presented at the very top of every doc in a distinct way to call attention to it.

The Summary at the top of a documentation article

Sidebar Metaboxes