 |
Today I get to write about something close to my heart: documentation. The emails I love the most start with, “I’ve got this new product. Please, document it!� I get a lot of pleasure from learning about someone’s code and making it as clear as possible for users. I love taking a great product and making sure that people get it.
In this article, we’ll look at writing documentation for a WordPress plugin, theme or product. Most of the information can be applied to documentation for other software types, but we’ll look at some WordPress-specific aspects.
In my experience, the quality of documentation in WordPress plugins and themes varies widely. From poorly documented plugins with one-line readmes to products with user guides, developer APIs and in-depth screencasts, you’ll find every type of documentation in the WordPress ecosystem. Many plugins and themes are built by developers who don’t have the time to write documentation or don’t have the money to pay a technical writer.
Unfortunately, the person who suffers the most from this is the developer. In a blog post, author and front-end developer Nicholas Zakas gives his number-one reason why good JavaScript libraries fail (quoted here — the original is no longer online):
Lack of Documentation:
“No matter how wonderful your library is and how intelligent its design, if you’re the only one who understands it, it doesn’t do any good. Documentation means not just autogenerated API references, but also annotated examples and in-depth tutorials. You need all three to make sure your library can be easily adopted.”
Taking Zakas’ statement as a starting point, let’s look at how to make sure your WordPress product can be easily adopted. We’ll look specifically at how to provide useful documentation to end users, with a brief diversion to writing for developers. But first, let’s dive into some learning theory.
Learning Preferences
A few years ago, I took a teacher-training course while teaching writing to adults. While I don’t teach much anymore, I still integrate an aspect of learning theory into my process when writing documentation. VARK is a theory of learning preferences. It’s an acronym of visual, auditory, read/write, kinesthetic.
VARK captures various preferences for taking in and implementing information where learning is the objective. This makes it extremely useful for writing documentation. Thinking about how your users process your information and how to make it as easy as possible for them is helpful. When writing, think about the different ways that people engage with and process the information your provide; VARK argues that there is a spectrum for the way people do that.
The VARK diagram.
To discover what your VARK learning preference is, you could take a short questionnaire. The results will place you in one of the four different modes — or you could be multimodal, meaning that you prefer a number of styles. There are different learning theories, but I find this one useful for thinking about the different types of documentation that I’ll need when working on a project.
In essence, VARK tells us that people learn in different ways, and in any pedagogical exercise we ought to think about how to make those ways as useful as possible. Let’s look at the different learning preferences and how to make sure you’re making full use of them.
Visual
Visual learners prefer to take in information that appeals to the eye. The VARK website lists the following as relevant techniques:
- Presenters who use pictures or gestures;
- Pictures, posters and slides;
- Books with pictures and diagrams;
- Flow charts and graphs;
- Highlighted text, multiple colors and underlining;
- Symbols and white space.
These suggestions relate to the classroom, but translating them to documentation is not difficult. Visual learners take a holistic approach, trying to see the whole picture rather than breaking it down into discrete parts. They might scan a whole tutorial or section of documentation before getting started to get a sense of the overall picture. Here are some suggestions for reaching visual learners:
- Use call-outs to draw attention to important tips and notes in the text.
- Include a lot of useful screenshots, writing on them and using highlights and call-outs.
- Use a flow chart to demonstrate a process.
- Highlight important pieces of text, and place key phrases in bold.
- Incorporate graphics that highlight your point.
- Create a screencast like SEOmoz’ Whiteboard Friday, which features a person speaking in front of a whiteboard.
Recommended documentation types: in-depth tutorials, screencasts, graphics, infographics
Aural
Aural learners absorb information through talking and listening. The VARK website suggests the following for these learners:
- Attend classes;
- Get involved in discussions;
- Explain ideas to other people;
- Use a tape recorder;
- Engage with interesting examples;
- Describe things to someone else second-hand.
Because online documentation is such a visual medium, figuring out strategies that would appeal to these learners is more difficult. However, with a little lateral thinking, including them is possible, too:
- Podcasts;
- Screencasts with detailed narration;
- Interesting, practical examples;
- A chat room such as WordPress’ IRC chat, support forums and screensharing on Skype (even though these are not documentation);
- Webinars.
As the list shows, even if your documentation is highly detailed, there will always be people who prefer to ask questions and have a discussion to find out what they need.
Recommended documentation types: tutorials, screencasts, podcasts, webinars
Read/Write
As you can imagine, read/write learners are pretty easy to target with documentation; they really love to learn by reading. But rather than just come up with big chunks of text, you should use variety to make things a little more interesting. Here are some suggestions:
- Lists;
- Headings;
- Dictionaries;
- Glossaries;
- Definitions;
- A large block of text;
- Essays;
- Manuals (computing, technical and laboratory).
While long pieces of documentation are a great way to engage these people, you could do a bit more work to really get them on board. Here are some suggestions:
- Use ordered and unordered lists;
- Make use of all heading tags;
- Include definitions in call-out boxes;
- Link to definitions elsewhere;
- Write a user guide;
- Write a glossary (the one in the WordPress Codex is a great example);
- Produce an eBook or manual.
Recommended documentation types: tutorials, eBooks, manuals, glossaries, references
Kinesthetic
Kinesthetic learners learn best by doing things. Rather than watch a demonstration, they want to get their hands dirty. Here are some methods from the VARK website:
- Using all senses (sight, touch, taste, smell, hearing);
- Going on field trips;
- Practical examples of abstract principles;
- Real-life examples;
- Hands-on approaches;
- Trial and error;
- Looking at collections of things (e.g. rock types, plants, shells, grasses, case studies);
- Exhibits, samples, photographs;
- Recipes (e.g. solutions to problems, previous exams).
Figuring out what types of documentation these people would like doesn’t take much imagination — tutorials would be a big hit. But go a bit further and you’ll find that producing documentation for kinesthetic learners can be really fun:
- Step-by-step tutorials;
- In-depth use cases;
- Links to practical examples;
- Real-life (rather than abstract) examples;
- Interactive learning tools, such as Codecademy;
- Short, practical tutorials such as those on WpRecipes;
- Webinars that walk participants through something practical.
Recommended documentation types: practical tutorials, tips and hacks, use cases
Multimodal
Around 60% of the population don’t fit neatly into any of these boxes. If this is you, then you are multimodal (i.e. you prefer two, three or even four categories). You tend to adapt your learning preference to the learners around you and to the medium you are presented with.
Also, it’s possible for your learning preferences to change, according to your life experience. A developer whose head is stuck in code, APIs and references all the time could easily start leaning towards read/write and kinesthetic learning.
The Point
The point of this diversion into learning theory is simple: to show that people learn in different ways; so, make sure your documentation appeals to all of them.
Sometimes clients tell me they just want screencasts. I ask if they have anything else, and if the answer is no, then I strongly recommend they look at other forms of documentation as well. Personally, I find screencasts very difficult to learn from; I prefer to scan tutorials for an overview before getting started. Everyone is different, and if you want your product to be usable by as many people as possible, then you need to think about all of these different learning preferences.
Thankfully, this is very easy to do. A walkthrough tutorial is a great way to appeal to every learning preference.
- Give kinesthetic learners something practical to do;
- Appeal to read-write learners with ordered and unordered lists, headings and call-out boxes for definitions;
- Call-outs are also appreciated by visual learners, and you can keep them even happier with a lot of graphics, diagrams and images;
- Practical examples will be helpful to aural learners; and to really tick off all of the boxes, you could include a brief screencast.
Don’t spend a lot of time agonizing about this when you get started with the documentation. Just be aware that variation is crucial.
What Types Of Documentation Are There?
As you’ve probably guessed, the umbrella of documentation is pretty large. Anything that documents your plugin, theme or product is documentation. Here are some examples of the types you might find yourself writing:
- Reference
- API reference
- Inline documentation and comments
- List of requirements
- Glossary
- Architecture or design overview
- Tutorial
- Manual
- Readme
- WordPress help menu
- FAQ
- Tooltips
- User guide
- Troubleshooting guide
- Screencast
- Book and eBook
- Quick hacks and tips
- Infographic
- Screencast
- Webinar
The types of documentation you adopt will depend largely on two things:
- Your product type,
- Your audience.
Many WordPress plugins and themes are developed specifically for end users, rather than being developer tools. With that in mind, let’s look in depth at how to produce effective documentation for end users.
Getting Started
Before getting started with any type of documentation, think about these things:
- Have you frozen the features?
Don’t write the documentation while you are still adding features and making major changes to the code. - Do you have a plan?
Write down a structure. Just as a designer would create a wireframe, it would be helpful to sketch out the structure of your documentation, both for individual pieces and for the overall architecture. It will bring a lot coherence to the documentation. - How steep is the learning curve?
If your product is complex, then you’ll need to guide users through the documentation, getting them to the beginners’ information first, through to the intermediate, then to the advanced. - Do you have access to the developer?
If you are the developer, then great; but if not, this is really important. Your first job will be to learn a product that likely does not have documentation, so you will need to ask the developer questions. There’s no point in starting a documentation project if the developer is about to go on vacation. - What is the purpose?
Is the documentation purely to assist users, or is it for marketing, too. A reference doc will be useless for sales, but you might want a tutorial to show off the product to potential customers.
The written word (Image: Arslan)
Here are some practical writing tips to keep in mind once you get started.
- Keep it simple.
It’s not an opportunity to get poetic or clever. The best technical documentation is clear, concise and engaging. - Refer to the user in the second person.
For example, “When you have logged into WordPress, navigate to the plugin’s admin screen.� Write as though the reader is sitting beside you and you are talking them through the process. - Stick to the point.
Don’t meander off topic because this can distract users. - Think about formatting.
Perhaps you want to use bolding for the key point in each paragraph, or perhaps for instructions. Be consistent in your formatting across the documentation. - Write in the present tense.
Again, as if you were talking to someone who is sitting beside you. - Think about tone.
I recommend friendly and engaging, but you might want the tone to match the rest of your website’s content. - Don’t be afraid of short paragraphs.
Stick to one major point per paragraph so that messages don’t get confused. - Be logical.
Drip-feed your information in a logical order to ensure that readers are able to follow. - Proofread.
And ask someone else to proofread for you. A fresh pair of eyes will pick up things you miss.
End-User Documentation
The end user is the person who will use your product. In the WordPress environment, I get asked to produce documentation for this type of user the most. There is a wide variety of end users, from total novices to savvy users to people who are developers themselves. If they are using (as opposed to developing) the product, we can consider them end users.
When writing documentation for end users, I always recommend aiming for the absolute novice. By doing this, you ensure that everyone is included. More advanced users can skim the doc and take what they need.
1. Research and Prepare
Before putting fingers to keyboard, spend time preparing what you are going to do and how you are going to do it. At this point, your software should be stable and just about ready to go. Rushing through the documentation process just to get it out there is tempting. But here’s some advice from Mike Pope, a technical editor at Microsoft:
“We’ve been known to tell a developer “If it isn’t documented, it doesn’t exist.â€� […] Not only does it have to be doc’d, but it has to be explained and taught and demonstrated. Do that, and people will be excited — not about your documentation, but about your product.”
Keep that in mind: good documentation makes the best of your software.
- Do you need an installation guide? If your product isn’t in WordPress’ theme or plugin repository, then I recommend preparing a generic guide to show users how to install the plugin or theme via the upload function in WordPress or via FTP.
- Plan everything beforehand. If your documentation will be big, think about the architecture. How will users navigate it? How will you present it?
- Draw a list of all of the resources that users will need (such as an FTP client or text editor). Link to the tools that you recommend.
- Choose the most appropriate documentation type for the product. You might want a general set-up guide or a specific tutorial. For an e-commerce plugin, you could have the following sections: “How to set up this e-commerce plugin� and “Selling your digital product with this e-commerce plugin.�
- Provide easy access to all of the resources and references your users might need. For example, when introducing a new concept, link to a relevant page either on your website or in the WordPress Codex.
- Anticipate questions users might have. If your users are diligent and read the documentation, then they will spend less time bugging you in the support forums.
- Think about how to integrate your documentation in WordPress’ administration screens. In WordPress 3.3, for example, the contextual help screens were improved, becoming a great place to assist users.
- Figure out your point, and stick to it. Don’t meander off topic, or else your message will get confused. The reader should come away with the key message.
- Do, however, offer examples and anecdotes that will help the user think about the main message from a different angle. This is a great way to emphasize a point.
2. Getting Down to Writing
Remember that the purpose of documentation is to help users use a product quickly and effectively. Step into the shoes of the layman end user and identify what they will need to do just that. Ask questions that an end user would have, and get confused and have doubts like an end user. Never assume that the end user should just know something; your job is to tell them.
Think of your documentation as a story. Like every good story, it needs a beginning, middle and end. Below is an overview of what to include in each part.
The introductory paragraph is crucial. It sets the tone for the documentation and should include the following:
- Introduces what you’re going to do;
- Tell the reader how you’re going to do it;
- List requirements (e.g. WordPress 3.3+);
- Summarizes what the reader will achieve by the end (if it’s a practical tutorial);
- Lists resources that the user will need to complete any practical sections.
The main body is the meat of the document. It’s where you get to the point and where your readers start to learn. Here are some tips for writing the main body:
- If you’re writing a user guide, break up the body into self-contained sections on different topics. Give each section a clear, relevant heading. A user guide on setting up a payment gateway could be broken down into “PayPal,� “PayPal Pro,� “Authorize.net,� etc.
- Tutorials should be laid out with clearly numbered steps, using headings. Each step should deal with one primary task and logically follow from the previous step. Include everything a user would need to complete the task. Ideally, an advanced user should be able to achieve what they need to do by scanning the headings, while novices can read through. A tutorial for installing a WordPress plugin via FTP might follow these steps:
- Download the plugin,
- Upload the plugin via FTP to
wp-content/plugins/, - Activate the plugin.
That would be enough for an intermediate user, while the main body text would help the novice.
- Use call-out boxes to highlight useful pieces of information. I tend to use them for these:
- Useful tips,
- Definitions and references,
- Important pieces of information that I don’t want people who scan to miss,
- Advanced tips for more experienced users.
- Use screenshots liberally. These are really useful for visual learners and people who like to scan.
- Think about including a screencast to provide either a demonstration or walkthrough tutorial.
- Use a variety of methods in one section of documentation to reach a wide audience: visual, read/write, kinesthetic and aural. This will save you from having to produce a different version for each learning preference.
- Use a syntax highlighter to improve code readability. If you’re writing your documentation in WordPress, a popular plugin is Syntax Highlighter Reloaded.
The conclusion sums up what you’ve done and provides any additional information:
- If the guide is massive with a lot of in-depth material, then the conclusion is a good place to remind the user what you’ve covered and what they should now be aware of. This could be a list of main points or takeaways.
- A practical tutorial could simply finish with a screenshot of what the user should have achieved or with a link to an example.
- Provide a list of resources or further reading.
- Provide a list of tutorials to take things further.
- Link to your support forums or feedback form.
3. Test, Revise, Update
Now that you’ve written the documentation, it’s time to test, revise as necessary and keep it updated.
If I’m writing documentation for a particularly challenging product, I’ll get a representative end user to test it for me. This is usually someone who is familiar with WordPress but not a developer. If it’s a tutorial, I’ll ask them to work through all of the steps as laid out and to highlight anything that’s confusing or that they struggled with. If you are using code snippets, they must be accurate, so explicitly ask your tester to implement them. For a user guide, I’ll ask questions that the tester should know the answers to.
Armed with the suggestions of the tester, I’ll move on to the next phase, revising, and I’ll also have a nice list of questions to include in the obligatory FAQ.
Read through your document and revise. Here’s what to look out for:
- If you have tested the documentation, incorporate any resulting changes.
- Get rid of wordiness. For example, “Now it’s time for you to visit the WordPress administration screens� could be revised to “Visit WordPress’ administration screens.�
- Fix all typos and grammatical errors.
- Add any links you may have missed.
The final step in the process is to update. This could be weeks, months or years after the documentation’s original production. In the world of WordPress, it is more likely to be months. Update the documentation to reflect changes in any of the following:
- WordPress’ UI (update screencasts and screenshots);
- New features or functionality in your product;
- New features or functionality in WordPress;
- User feedback.
A helpful plugin that I use to track documentation updates is Content Audit. It uses custom taxonomies to help you categorize your content. Being able to mark sections as needing updating straight from WordPress’ UI is helpful. You can also assign WordPress users to be responsible for various pieces of content, as well as write inline comments.
Let’s look at a case study of an end-user documentation project that I recently completed.
Case Study: ManageWP
I was approached by ManageWP at the end of 2011 to rework its documentation. At the time, the documentation was pretty thin and contained numerous grammatical and spelling errors. Here’s what Vladimir Prelovac had to say about it:
“Our initial documentation left a lot to be desired. We did not have it organized in a systematic way, and most topics were added ad hoc. It was hard to search, and it contained a lot of errors as it was sometimes not written by a native speaker.”
At a glance, the documentation looked to be in need of a total rewrite. Here’s the workflow I adopted:
- I carried out a full review of the existing documentation and listed challenges and recommendations:
- The documentation was listed alphabetically. This meant that a new user had no logical order to follow. Everything was jumbled together, making items difficult to find.
- Many of the paragraphs covered multiple points, making them difficult to follow.
- There were no screenshots.
- The formatting did not vary, making the text difficult to read.
- I recommended restructuring the documentation to make it more logical (for example, starting with “Getting Started� and then moving through different sections).
- I put together a Google spreadsheet listing all of the existing guides, noting the new ones and splitting them up into sections. Vladimir, CMO James Mowery and I reviewed the order to make sure we were all happy.
- All of the user guides were rewritten according to the principles outlined above.
- We reviewed the docs to add sales and marketing content.
- We made the layout and design of the user guide more intuitive for novice users.
You can see the result by checking out ManageWP’s user guides. In the future, we’ll improve the documentation by adding videos that complement the text.
The current incarnation of ManageWP’s user guides.
A Note On Developer Documentation
While end-user documentation is for the people using your plugin or theme, developer documentation is for the people who will be developing, forking or extending it. I get many fewer requests for WordPress developer documentation; I suspect this is primarily because most WordPress developers and designers are producing for end users. Occasionally I am approached to work on documentation for a project for both developers and end users, and I’ll look at such a case below.
My strongest recommendation is to keep the documentation for end users and developers separate. End users don’t need to see developer docs; that would only confuse and, in some cases, intimidate them. Of course, nothing prevents each group from using the other’s documentation, and the groups are not mutually exclusive, but clearly delineating between the two types is important, even if just with a prominent notice, as the WordPress Codex does.
A beautiful example of developer documentation is the recently launched QueryPosts, which is an easily searchable repository of WordPress code.
If you are generating extensive documentation for developers, check out some of these tools:
- phpDocumentor,
- Pears (a WordPress theme).
bbPress and Its Beautiful Inline Documentation
The bbPress plugin has one of the best examples of inline documentation. Below is an extract from the bbpress.php file, which loads the translation file for the current language.
/**
* Load the translation file for current language. Checks the languages
* folder inside the bbPress plugin first, and then the default WordPress
* languages folder.
*
* Note that custom translation files inside the bbPress plugin folder
* will be removed on bbPress updates. If you're creating custom
* translation files, please use the global language folder.
*
* @since bbPress (r2596)
*
* @uses apply_filters() Calls 'bbpress_locale' with the
* {@link get_locale()} value
* @uses load_textdomain() To load the textdomain
* @return bool True on success, false on failure
*/
public function load_textdomain() {
// Allow locale to be filtered
$locale = apply_filters( 'bbpress_locale', get_locale() );
// Get mo file name
$mofile = sprintf( 'bbpress-%s.mo', $locale );
// Setup paths to current locale file
$mofile_local = $this->lang_dir . '/' . $mofile;
$mofile_global = WP_LANG_DIR . '/bbpress/' . $mofile;
// Look in local /wp-content/plugins/bbpress/bbp-languages/ folder
if ( file_exists( $mofile_local ) )
return load_textdomain( 'bbpress', $mofile_local );
// Look in global /wp-content/languages/ folder
elseif ( file_exists( $mofile_global ) )
return load_textdomain( 'bbpress', $mofile_global );
// Nothing found
return false;
}
This kind of inline documentation would be helpful to you and to other developers using your code. At a glance, a developer can tell what the code does and see specific instructions (such as to place custom translation files in the global language folder). For an open-source product, this makes the code much more usable to a wider array of people. Read what developer John James Jacoby has to say about this on his blog.
The developers I have spoken with who take inline documentation seriously stress that you should write inline documentation as you are coding, for several reasons:
- If you are developing alone, you will write the documentation faster;
- A third party will find it much easier to write the documentation;
- You can return to the code in the future and instantly remember what you did;
- Other developers will be able to easily fork your code.
Case Study: Infinity Theming Engine
I was approached by PressCrew to help out with the website content and documentation for its Infinity theming engine. From the start, the developers, Bowe and Marshall, and I knew that it would be a challenge. Unlike everything else I’ve used in WordPress, Infinity uses configuration files to turn features and options on and off. It also supports crazy features such as infinite child themes, which took a mental leap to conceptualize how it could be used.
We spent a considerable amount of time identifying our audiences and figuring out what features to pitching to each. We asked ourselves some questions:
- What would the average WordPress user use Infinity for?
- Do we want average WordPress users to be able to make use of Infinity’s most powerful features?
- What information will developers need in order to make full use of Infinity?
- How can we make the documentation useful to developers?
- How do we give developers confidence in Infinity?
With our users identified, we also needed to provide them with two sets of documentation, each with its own strengths:
- Demonstrative
Because we needed to introduce developers to a different way of thinking about WordPress — using.inifiles instead of messing directly with PHP — we wanted to introduce the concept in a fun way. Bowe came up with minions; a cast of characters each of whom would introduce a configuration file. We used humor and pop culture to make Infinity fun to learn about. Check it out.
Infinity’s minions. - Practical
Once the developer has learned what Infinity can do, they need to be able to easily do it. Marshall documented every function and then used phpDocumentor to create documentation from all of the source code. The documentation is written in Markdown and then parsed to both the theme and the library, so it has to be updated only once. As well as offering access from the library, Infinity includes documentation in the dashboard so that developers can access it while working on their theme.
Infinity’s UI
A major difficulty has been the speed at which Infinity is updated. Bowe and Marshall asked me to come on board in the beta phase, which saw massive changes. Any docs I wrote would be out of date within a few weeks. I asked Bowe and Marshall what advice they would give to other developers in a similar situation:
“Our advice would be to write down a basic outline of the feature you want to create. When the feature has made it into your product, really take the time to properly document it based on your outline BEFORE you move on to the next feature.”
With a major project like Infinity, an iterative approach is best, documenting as you write the code. Then, after the features have been frozen, you would create the demonstrative documentation.
Conclusion: Sisyphus and I
In Greek mythology, Sisyphus is a king who was condemned to roll a boulder to the top of a hill. Every time he is about to reach the top, the boulder rolls back to the bottom. Up he goes to the top, only for it to fall back down again, and again, for eternity. That’s documentation writing.
With WordPress constantly changing, the documentation for WordPress constantly changes, and so the documentation for anything based on WordPress has to change, too. This could be anything from documentation for full-blown new features to screenshots to reflect UI changes. For me, the most painful moment is when WordPress releases a major UI change. I have to replace all of the screenshots — and screenshots are the most time-consuming part of documentation. Having a process in place, however, takes a lot of the pain out of it. But updating is important indeed because out-of-date documentation gives the impression of out-of-date code.
Don’t assume that your documentation is finished. It’s never complete!
Further Resources
- “Writing End-User Documentation in an Agile Development Environment,� Anne Gentle
- “The Six Pillars of Complete Developer Documentation,� Pamela Fox
- “If It Isn’t Documented It Doesn’t Exist,� Jeff Atwood
WordPress-Specific
- “Incorporating Contextual Help and Support into WordPress Themes,� Chip Bennett
- “New in WordPress 3.3: More Useful Help Screens,� Otto on WordPress
- “How to Improve Your WordPress Plugin’s Readme.txt,� Siobhan McKeown
- “Inline Documentation,� John James Jacoby
(al) (il)
© Siobhan McKeown for Smashing Magazine, 2012.
