A few months ago I wrote an article for Smashing Magazine on Writing Effective Documentation for WordPress End Users. One of the points that I made was that documentation should not be written until there is a features freeze. A commenter responded:
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.
At the time I was all “ugh, I’ve got this wrong and now I look like a doofus”, but I still feel that documentation in the WordPress context should be carried out towards the end of the development process. Working with so many WordPress and other businesses has convinced me that I’m right.
In an effort to refine my own processes, I’ve been doing a lot of research into different documentation practices. In doing the research I’ve discovered that all along I’ve been taking an agile approach to documentation writing and that (yay!) I was right about the whole features freeze thing. This doesn’t mean that you shouldn’t get your writer involved earlier, the commenter is right that the documentation writer is essential to the development process as they bring the user’s perspective, but writing shouldn’t start until a features freeze.
To celebrate, I thought I’d write an essay about why an agile approach to documentation is the best (and only, from my perspective) approach to documentation WordPress products. Extrapolate to other products as you will, though I’m focusing really on WordPress.
What is Agile?
Agile is an approach to development that is based on iterative and incremental development. In 2001 a whole bunch of developers met in Utah and came up with the Manifesto for Agile Software Development. The aim of the manifesto is to find better ways to develop software. It has four core principles:
- Individuals and interactions over processes and tools
- Working software over comprehensive documentation
- Customer collaboration over contract negotiation
- Responding to change over following a plan
The second principle, working software over comprehensive documentation, might freak the professional documentation writer out. After all, with less documentation what happens to our jobs?
I like to see it differently. Less documentation is a good thing. Users don’t read documentation. How many times have you answered a support forum request with a link to the documentation? How many times has someone tweeted a question when there’s an answer in the WordPress Codex? This can be frustrating for someone who provides support, and for the person who writes the docs – after all, it sucks when no one reads your writing.
But seriously, who wants to read a big documentation manual? who wants to read thousands of words in which you document your theme? It’s boring. It’s more fun to get started and break stuff.
What is Agile Documentation?
The best way to describe what agile documentation is, is to paraphrase what I think are the critical points for WordPress from Scott Ambler’s excellent Agile/Lean Documentation: strategies for agile software development
- Communication, not documentation
- Write documentation only if it’s the best way to achieve a goal
- Document stable things, not speculative things
- Let your documentation evolve: look for feedback, act on it
- Choose someone to own a document
- Be concise: choose roadmaps and overviews instead of detail
- Travel light
- Aim for just barely good enough
- Comprehensive documentation != success. It can increase your change of failure.
- Documentation is as integral to the system as the source code.
- The documentation’s benefit’s much outweigh the cost of creating and maintaining it.
- Developers rarely trust documentation, especially if it’s detailed as it can be out of sync with the code
- Each system has its own documentation needs.
- Ask whether you need documentation, not whether you want it.
- Create documentation at the appropriate point in the life cycle.
- Update only when it hurts
Hopefully from that list you get the sense that agile documentation is light-touch, written when it’s needed, and written iteratively, based on user feedback.
Why Agile for WordPress?
WordPress has a fast release cycle – you can expect a new version, with new features at least twice, perhaps three times, a year. That means that the documentation changes regularly. One major change, such as the new menu feature in WordPress 3.0 or the new media uploader in 3.5, affects products across the ecosystem. WordPress themes and plugins that rely on WordPress features will also need to have their docs updated. WordPress themes often have fast release cycles, and plugin developers are forever adding new features.
I worked with a client on a major documentation project, only for them to change how the framework worked when I was about to finish. That meant that large swathes of the documentation were no longer relevant. That’s a waste of my time and the client’s money.
Taking an agile approach mitigates against these issues. In fact, I think it’s the only way to work in the speedy world of WordPress. If you ask me to write documentation for you, I’ll be taking an agile approach. With that in mind, here are some best practices I follow to ensure that documentation is useful and agile.
Agile Best Practices for WordPress
Focus on user experience and user interface
A lot of the work I do as Words for WP involves ensuring that the information that the user needs is communicated through the user interface. Ideally, the user should be able to carry out basic tasks without leaving their user interface. Documentation should only ever be an aid. It is no replacement for a user interface that creates a seamless user experience. Beautifully crafted documentation along with a crappy UI is dumb.
Improving the UI can involve everything from ensuring that fields have clear labeling, to mapping out different user journeys beforehand. I use Balsamiq to create mockups of how the user with work through the UI, and also how they will work with the documentation. This sort of high level planning pays dividends in terms of enhancing your users’ experience.
Produce as little documentation as possible
Give your users the documentation that they need to get the job done. If it’s setting up a theme guide them through the setup. Don’t clutter your documentation with stuff your user doesn’t need to achieve their goals. Avoid being too comprehensive. Keep in mind that the user won’t read it, especially if it’s too long.
I like to think in terms documentation layers:
- The top level provides what your user needs to achieve their primary goals – setting up the theme or plugin.
- The second level provides additional learning, this could be supporting tutorials or links to more advanced topics.
The top level is the most important. Everything else is nice to have. It could even come in the form of tutorials or articles on your blog.
1,000 words is always better than 5,000. Too much documentation leads to various problems:
- You have to keep it updated. If there is loads of documentation it will get out of date quickly
- Users won’t read it.
- Too much work!
WordPress itself has its own resources that you can use for supporting documentation. Tell your users how to set their pretty permalinks and provide a link to the codex for people who want to learn more.
Update when it hurts
Not every release of your software requires that you update your documentation. For example, if there are changes to the colours of the UI you don’t need to spend hours retaking screenshots. If the user can do everything that they need without you having to update things, then don’t bother. If a major feature, however, is introduced, then you need to get updating. Take a look at your docs and ask whether the user can still achieve what they need. If they can’t, update; if they can, go drink beer.
Know your audience
You should approach developer and user documentation as two separate entities. The aim of user documentation is to help your user use your product, the aim of developer documentation is to enable developers extend and develop your product. User documentation will not help developers extend, developer documentation will not help users do what they need. If the different groups have a need then they can refer to the other docs. By mixing the two up you confuse users and force developers to sift through content to find what they need.
You should also try to get a sense of the types of users that you have. If your product is for more advanced WordPress users then aim your documentation at them, for novice users you’ll need to keep things simple and cover the basics.
Don’t document unless you have to
If everything that your user needs is self-evident from the UI then why bother documenting? You’re adding a whole level of unnecessary work for yourself. Most of the plugins and themes I encounter require some documentation, but they don’t need to be comprehensive. Aim for an intuitive user experience and helpful user interface, document to support that.
Test and iterate
Documentation is for your users, whether they be users or developers. It should adhere to usability standards. Test your documentation and ask for feedback from your users. If they are having issues fix the documentation. WordPress developers have excellent access to their users, usually via a support forum but you could have a feedback tab in your documentation to ask your users to report issues. Listen to your users – that’s who you work for.
A trick that I like to employ is to give documentation to my husband and get him to work through it. If he can do it, anyone can. If you’re writing more advanced documentation find someone at the appropriate user level.
Document your code inline
Documenting your code is awesome. It makes your code easy for other developers to work with. It helps documentation writers like me to look at what you’ve done without bothering you for more information. And it makes it easier for you to understand what you’ve done when you return to the code after a break.
If you have great inline documentation then a tool like phpDocumentor will be able to spit out all of the developer documentation that you need.
Make notes as you code
Making notes as you code can be really useful for documentation writers. Just noting stuff down will speed up the documentation process as the writer won’t have to go hunting for information. Memory is frustrating. You may think that you’ll remember something important but it’s easy for things to slip your mind. Even the scrappiest of notes make for a great resource.
Document stable things, not speculative things
If you want Words for WP to write your documentation, get in touch with me when you’ve reached your first beta (or earlier, but only if you want to check my diary). Writing should start when you reach release candidate. Don’t waste time documenting things or taking screenshots when your product still might change. I’ve had this happen a number of times and it doesn’t make anyone happy.
Have a document owner
It makes sense to have someone who is responsible for ensuring that your documentation gets created and is updated. I’d normally recommend that this is the lead developer. By own, I don’t mean “write”. The document owner can update docs themselves or assign someone else to do it. It makes sense for the person who knows the plugin or theme inside out to be in charge. They’re the one who knows what needs to be changed when an update is released.
This is perhaps one of the most important best practices. If you’re not adding value stop what you’re doing. It doesn’t add value to describe every field in your UI with things like “Address: insert your address” or “The products area is where you add your products.”
Everything that you do should add value to the user. If it doesn’t, ask yourself why you’re doing it. If you’re fanatical about being comprehensive, stop. Slap yourself about the face. You’re not only wasting your time but you’re making a worse experience for your users, and making them less likely to read it.
Create a Workflow
Creating a useful workflow means that your documentation is updated as painlessly as possible. I always recommend that WordPress businesses use WordPress to create their documentation section. You can’t beat a Docs custom post type with a page template for displaying a top level table of contents. Custom taxonomies can be used to organise the content. Use a hierarchical taxonomy for displaying content on the front end, and use a non-hierarchical taxonomy for flagging documents that need to be updated. You could use a plugin like Edit Flow or Content Audit to streamline your workflow and allow for editorial comments on individual documents.
My final tips for writing WordPress docs
- Do some research amongst your users to see what they do and don’t need
- Strip out everything superfluous
- Think user experience
- Have an awesome user interface
- Complement your documentation with tutorials, use cases and hacks on your blog. This is a great opportunity to create dynamic content. Link to these in your docs (but don’t use your blog for essential stuff!)
- Write documentation that is useful for your users
- Keep your documentation action-based
- Separate developer and user documentation
- Test your documentation – if it doesn’t work, ditch it
- Always, always, think about your user
- Agile/Lean Documentation: Strategies for Agile Software Development
- Best Practices for Agile/Lean Documentation