Menu Search
Jump to the content X X
SmashingConf London Avatar

We use ad-blockers as well, you know. We gotta keep those servers running though. Did you know that we publish useful books and run friendly conferences — crafted for pros like yourself? E.g. our upcoming SmashingConf London, dedicated to all things web performance.

Writing Effective Documentation For WordPress End Users

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.

splash image1

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.

Further Reading on SmashingMag:

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 Zakas6 gives his number-one reason why good JavaScript libraries fail (quoted here7 — 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 Link

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. VARK8 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 questionnaire9. 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 Link

Visual learners prefer to take in information that appeals to the eye. The VARK website lists10 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 Friday11, which features a person speaking in front of a whiteboard.

Recommended documentation types: in-depth tutorials, screencasts, graphics, infographics

Aural Link

Aural learners absorb information through talking and listening. The VARK website suggests12 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 Link

As you can imagine, read/write learners13 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).
picture of a big14

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 Codex15 is a great example);
  • Produce an eBook or manual.

Recommended documentation types: tutorials, eBooks, manuals, glossaries, references

Kinesthetic Link

Kinesthetic learners16 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 Codecademy17;
  • Short, practical tutorials such as those on WpRecipes18;
  • Webinars that walk participants through something practical.

Recommended documentation types: practical tutorials, tips and hacks, use cases

Multimodal Link

Around 60% of the population don’t fit neatly into any of these boxes. If this is you, then you are multimodal19 (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 Link

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? Link

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 Link

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.

A picture of pens and some writing
The written word (Image: Arslan20)

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 Link

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 Link

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 Pope21, 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 Link

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,” “,” 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:
    1. Download the plugin,
    2. Upload the plugin via FTP to wp-content/plugins/,
    3. 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 Reloaded22.

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 Link

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 Audit23. 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 Link

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:

  1. 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.
  2. I recommended restructuring the documentation to make it more logical (for example, starting with “Getting Started” and then moving through different sections).
  3. 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.
  4. All of the user guides were rewritten according to the principles outlined above.
  5. We reviewed the docs to add sales and marketing content.
  6. 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 guides24. 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 Link

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 does26.

A beautiful example of developer documentation is the recently launched QueryPosts27, which is an easily searchable repository of WordPress code.

If you are generating extensive documentation for developers, check out some of these tools:

bbPress and Its Beautiful Inline Documentation Link

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( '', $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 this29 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 Link

I was approached by PressCrew to help out with the website content and documentation for its Infinity30 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 .ini files 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.31

    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 Link

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 Link

WordPress-Specific Link

(al) (il)

Footnotes Link

  1. 1 /wp-content/uploads/2012/06/splash1.jpg
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
  8. 8 #
  9. 9
  10. 10
  11. 11
  12. 12
  13. 13
  14. 14 /wp-content/uploads/2012/06/readwrite.jpg
  15. 15
  16. 16
  17. 17
  18. 18
  19. 19
  20. 20
  21. 21
  22. 22
  23. 23
  24. 24
  25. 25
  26. 26
  27. 27
  28. 28
  29. 29
  30. 30 #
  31. 31 #minions/
  32. 32 #minions/
  33. 33
  34. 34
  35. 35
  36. 36
  37. 37
  38. 38 /2011/11/23/improve-wordpress-plugins-readme-txt/
  39. 39

↑ Back to top Tweet itShare on Facebook

Siobhan McKeown is a big fan of words, and of WordPress, which works out pretty well since she runs Words for WP, the only copywriting service dedicated to WordPress service providers. You can find her on her personal blog, twitter and occasionally hanging out on G+.

  1. 1

    Nice! :) I hope readers also noticed you have this article laid out the same way – nicely section, numerical instructions and bullet points. ;D

    A quick tip for devs: if users are consistently asking the same questions, you need to write the docs for it, fix the UI, or make those docs easier to find.

    I’m also finding documentation and support a growing area. If you;re good with using WP and figuring things out, I’m seeing more commercial places and devs shops hiring support and docs teams.

    • 2

      Yeah, that’s a great point – if the same issue is coming up again and again then you know that it’s not being explained properly or is too hard to find. It’s the developer’s responsibility to make sure the product is understood.

  2. 3

    Hollywood Cat

    July 5, 2012 4:03 am

    Thanks for this article. It’s a shame the WordPress Codex does not contain more examples. Tend to give up and try and find info elsewhere, like here!

    • 4

      Thanks for the comment Hollywood Cat. The WordPress Lessons section of the Codex is a great place to find helpful examples. Also, if you do find what you need elsewhere, you could think about integrating what you’ve found with the codex to help more people in the future.

      • 5

        Hollywood Cat

        July 6, 2012 3:49 am

        Thanks for the tip Siobhan. I have just discovered – just what I was looking for.

  3. 6

    It’s would be very nice, if someone share methods of documenting JavaScript. Here is a lot of examples for JSDoc, for example, but it’s hard to get how implement it with the code, based on free libraries like jQuery.

  4. 7

    Thanks for this. This was very helpful especially the “End-User Documentation” Section.

  5. 8

    Martin Metzmacher

    July 5, 2012 7:08 am


    Really comprehensive, useful guide!

  6. 9

    I first heard about the theory of learning styles almost thirty years ago when some people proposed it after looking at MRI data collected from brain injured patients.

    However, there is no peer-reveiwed research to support the theory of learning styles, and there is a lot of research that says it is junk science.

    Don’t get me wrong, we do have different talents, and we remember and process information differently, but research has shown that it makes no difference how we actually receive the basic information.

    “Students do have preferences about how they learn. Many students will report preferring to study visually and others through an auditory channel. However, when these tendencies are put to the test under controlled conditions, they make no difference—learning is equivalent whether students learn in the preferred mode or not. A favorite mode of presentation (e.g., visual, auditory, or kinesthetic) often reveals itself to be instead a preference for tasks for which one has high ability and at which one feels successful.”

    – Change – The Magazine of Higher Learning

    Some resources:

    Riener, C., & Willingham, D. (n.d.). Change Magazine – September-October 2010. Change Magazine — May/June 2012: In This Issue. Retrieved July 5, 2012, from

    Paschler, H., McDaniel, M., Rohrer, D. and Bjork, R. (2010) Learning styles: Concepts and evidence. Psychological Science in the Public Interest 9, pp. 105-119.

    Roediger, H. L. and Karpicke, J. D. (2006) The power of testing memory: Basic research and implications for educational practice. Perspectives on Psychological Science 1, pp. 181-210.

    Learning styles. (2012, June 21). In Wikipedia, The Free Encyclopedia. Retrieved 16:56, July 5, 2012, from

    Revell, P. (2005, May 30). Each to Their Own. The Guardian. Retrieved July 5, 2012, from

    • 10

      Thanks for your comment. I’m sure you’re right about learning styles – VARK, however, is to do with learning preferences as opposed to learning styles. So it is more to do with the way that individuals prefer to take in a deal with information, as opposed to any specific theory of styles. That said, I’m not wedded to it and I am sure that there are competing theories, I just find it a very helpful framework to use when thinking about how to create a documentation project that lots of people will find useful and enjoy learning with.

  7. 11

    Beautifully laid out article as also the ideas for written documentation. It is very hard to do that well.

    Only thing that bothers me is the general approach to WordPress Code documentation. Though the official WordPress Codex states it, the criticism about inline-documentation rises. It might be good practice to just document the really unreadable parts of written code. Lines as

    // Nothing found
    return false;

    actually decrease code readability and at last code quality, as you care less about readable code without inline-documentation. Actually you see this a lot when working in WordPress-Theme files. Maybe a well written documentation might replace this some time…

    • 12

      I would agree that getting rid of redundancy is a good idea. For example,

      //Nothing Found
      return false;

      – that’s fairly self-evident as to what is happening, even to a non-coder.

      However, you also need to strike a balance between getting rid of redundancy and providing information that is useful to coders at all levels. Something that is self-evident to an experienced coder may need an explanation for someone with less experience. In an open-source project such as WordPress I think this is particularly important, where code is being forked and changed regularly.

  8. 13

    I’m a professional tech writer, and this is a great article for those wanting to learn more. I have a few points I’d like to share:

    “people learn in different ways; so, make sure your documentation appeals to all of them.”
    This is a nearly impossible task. It’s why the help/documentation you’ve looked at in the past never solves your particular problem. There’s no one-size-fits-all approach; you have to know your users and their skill level.

    “Don’t write the documentation while you are still adding features and making major changes to the code.”
    I disagree with this statement. Tech writers are often also the sole user advocate in your organization. The sooner you get them in, the better your product will look and feel. Writers will ask questions from a user perspective that you may never have anticipated. From a workflow perspective, if you wait until the product is “done” to start documenting, then the writer is always behind, and so is your documentation. When the doc doesn’t match the UI, users get frustrated, and your support calls increase.

    “Do you have access to the developer?”
    This is IMPERATIVE from a documentation perspective. No one understands functionality like the person who wrote it, and more often than not, the writer is far less techie than a dev. To truly understand software, writers need to understand what it’s supposed to do, have full access to an alpha- or beta-version, and then bring those often-annoying questions to the developer.

    Also to note based on my years of experience: devs are generally not good writers, and writers are generally not good devs.

    “When writing documentation for end users, I always recommend aiming for the absolute novice.”
    I will generally agree with this, but again, know your user. If you have an existing site, analytics will help you figure this out.

    Finally, remember that no one is going to your documentation because they’re bored and like reading dry material. They’re looking to get in, find a specific solution, and get out.

    Thanks again for a fine story on our profession.

    • 14

      Thanks for your comment Ed.

      Yes, it is a pretty impossible task to reach absolutely everyone but it’s definitely something to aspire to. You’re right that it’s a matter of knowing who your users are. In some cases this is possible (if the product is already being used) and in other you’ve got to do some research beforehand. Also, some products are trying to appeal to new audiences so you’ve got to think about the new audience and the old audience.

      The same goes for your comment about writing for the absolute novice. A novice developer is going to have a totally different skill level to a novice internet user. That’s like the difference between writing docs for my mum and for me – we’re both novices in some cases but our experiences are worlds apart.

      The features freeze thing is based on my own experience of running into problems again and again with developers making changes in the middle of my writing project and sending me back to the drawing board. However, I’m definitely willing to have my mind changed on it. I think it comes down to the size of the project – in general, WordPress plugins, themes and services are fairly small – even the most comprehensive plugins are nothing compared to WordPress itself. I can imagine that the situation would be quite different for bigger projects, especially those with tighter project management.

      Glad you enjoyed the post! :)

    • 15

      You, Sir, stole the words from my mouth. Those were the very things I was going to point out. To add to the don’t-write-documentation-until-code-freeze bit, I would say that having worked in offshore development centers, it’s impossible to implement that for two reasons: (1) The time between code freeze and a version (or patch) release is barely enough to document one-thirds of the features going into the new product (even in an Agile environment, where a release happens every 2-3 months) and (2) in some organizations, the definition of “done” for a feature includes the clause that the documentation be marked as complete by the product manager/owner. It’s a part of the process. Only after this does the feature go for final testing. Believe it or not, this is a practice! And a good one at that because the writer/s don’t have to wait till the very end for the work to be dumped on them.

      Siobhan, thanks for the neat article. I loved how you’ve mapped VARK with technical writing. A very nice approach!

      • 16

        Thanks for your comments, Dee. It’s really interesting for me to hear how this sort of work is done in big development centers. Largely I work with SMEs who are producing plugins and themes, often there is no project manager other than the developer who has realised at the last minute that they need to get some documentation together. In many cases, the product started out as a hobby and the developer realised that they could monetize it – when they decide to start making money the realise they need docs.

        Occasionally I’ll work with developers who are half way through a project and realise that they need to get started. However, we have had major problems with developers deciding to change direction in their beta phase (or before). This is no doubt down to project management – a developer sees a shiny thing and wants to implement it straight away. There’s no one to say stop.

        That said, I would really love for a developer to get me on board at the start of the project so we could work out documentation beforehand and we can go through the process together. I think for WordPress products to really start reaching large-scale they do need a team behind them from the ground-up.

  9. 17

    I believe every product should be designed and build in a way that documentation needs to be as small as possible.

    If people buy a theme or plugin with admin options that are build and designed with usability in mind, most of the time people can jump right in and start enjoying their purchase.

    Good usability design = less documentation = more fun!!

    That’s the way i do it and think is best.

    • 18

      It’d be nice if that was possible. Certainly simple and streamlined products may be able to get away without documentation. But many WordPress plugins are created for a wide user base and have loads of settings that need to be customized to make that plugin work for a particular use-case. It’s unfortunately not always possible to reach all of your audience just through the UI.

      • 19

        Yeah your right about that.

        But i think that’s also the problem with some plugins.
        They want to reach too many things at once and automaticaly it becomes bloated with tons of settings. And tons of settings are cool for other tech-savy endusers who like it: the more settings it has the cooler it is for them.

        But creating something for a ‘normal’ end user, almost everything could be cut down in understandable pieces with as less documentation required as possible.

        But still you’re right, sometimes it’s just not possible – unfortunately

        • 20

          Yes, I don’t think it’s possible in the scheme of enterprise (software) applications.

  10. 21

    As a WordPress user and a fairly technically literate one I find it frustrating that much of the documentation is very light-on and assumes a lot of coding or PHP knowledge. It can be very frustrating.

  11. 22

    Thank you Siobhan for the extensive post on how to approach and write documentation for WordPress based websites.

    Do you recommend any of the WordPress plugins which allow you to write site notes which website owners can access from the back-end? I have used. I have used Dashboard Site Notes plugin in the past and I have found it to be fairly OK. However, I have not explored the possibility of creating a full instruction manual using the plugin. I was wondering if you have had the opportunity to try any of the plugins and how was your experience.

    Thanks and Regards

  12. 23

    Thank you for demonstrating what great documentation can be.
    Do you have suggestions for what themes lend them selves particularly well to process documentation projects?

    Thank you.

  13. 24

    This was a good article. Thanks!

  14. 25

    Brilliant, just what I was hoping to find. I have three fairly large client wordpress sites which are about to go live and now I have to sit down and document everything. They all operate on different levels, have a vast amount of custom fields, taxonomies & features.. This gives some inspiration to get them done. As a developer, motivation for this seems like an uphill struggle.

    Many thanks


↑ Back to top