This approach may have a steady stream of content on your blog, but it’s not useful, distinctive, or even particularly relevant to your company. There are plenty of generic WordPress blogs out there, producing content about WordPress, and doing a pretty good job of it – why try to be like them? Why product sub-par content just for traffic?

Rather than thinking of your blog as a traffic generation tool, think of it differently:

1. a place to show off your knowledge of your area
2. a home for your community
3. a repository of learning
4. a showcase for your products
5. a showcase for your community

I don’t do a whole lot of blogging anymore, and if someone asks me to help them out with their blog, I’ll often suggest that we think about strategy before starting to write. Ideally I’d like to provide them with the tools to create a sustainable blog. This approach pays dividends as it creates a long-term strategy that can be built upon.

Here are some of the things I’ll look at when putting together a blog strategy for a WordPress business.

Credibility

Your blog is your opportunity to establish your credibility. You can show off just how much knowledge you have in your subject area. As people who work on the internet we’re very lucky to have a platform to showcase our skills. Think about more traditional modes of business – a mechanic, for example. I have no idea whether my local mechanic is any good, except recommendations and reviews. A mechanic doesn’t have a forum to be all “Oi! Look at my crazy mechanicing skills.” You do have that.

Show off what you do, write elegant posts that make it clear that your businesses comprises experts in your field. For example;

• Theme Shop – articles about workflow, design decisions, issues you’ve faced, design trends, why you’ve chosen specific functionality. Articles about theme development and theme design.
• Hosting company – performance, caching, servers, reviews of CDNs, optimizing WordPress, .htaccess, nginx vs apache, working with MySQL.
• Maintenance & support – WordPress maintenance tasks, keeping WP secure, running your WordPress site effectively.
• Content (i.e. me!) – posts about producing content for WordPress businesses (like this one, duh), documentation, UI text, UX, general posts about tech writing.
• Development shop – coding, development, troubleshooting, articles about any area of WordPress you specialise in – i.e. Multisite, BuddyPress,

Whatever you do, whether it’s WordPress or anything else, use your blog to establish your credibility, not to look like a spammy SEO person.

Community

Part of the issue of going down the SEO route is that it makes it harder for a community to form around your blog. Ideally, your blog should provide a hub for your customers and your community. If you’re just providing them with content they could find anywhere then you’re not giving them an incentive to make your blog their online home. There are a number of different ways you can engender a sense of community around your blog:

Transparency

Don’t just be a shop front. Lift the veil and show what’s going on behind your business. Let people feel that they’ve got a stake in your business, and in the people behind it. This will help to create loyalty. You can achieve this by sharing your successes and your failures, by discussing major changes. By being upfront and honest with your community, major issues such as hacks or other security breaches, can be turned into PR successes. People like it when companies admit that they’re wrong and try to do better. All of these things will help people to feel that they are part of your family.

Feedback

Many of your customers or clients will have absolutely no contact with the wider WordPress community. Why would they? To them WordPress is just a tool to achieve their business goals. This means that you should provide any WordPress news that is relevant to your readers. A particularly good time to do this is when a new WordPress Release Candidate appears. Write a post about what the changes mean for your customers. Things like the new media uploader are going to be relevant to everyone, performance improvements might be of particularly interest to hosting providers, new functionality or under the hood improvements could be relevant to plugin developers and development shops. Keep your customers up-to-date, this means no surprises when they upgrade.

Case Studies

Case studies are effective for so many reasons. Here are just a few:

1. They show off what your product can do in an actual, live example.
2. They make your customers feel good. They will be flattered if you ask to do a case study on them.
3. They’re a useful way for your customers to learn.

When you put together a case study on a customer you’ll naturally ask about how the user has implemented your product on their website. Why did they choose it? How did they set it up? Did they customize it? What plugins did they use with it? etc etc etc. But also spend some time looking at how the product affected their offline business. If you sell an event management plugin, get the user to take photos of the event, to get quotes from people who used the website to make their booking. Always include photos of people!

Figurehead

Another way to strengthen your community, is to have a figurehead. In the WordPress community this is most commonly the founder (or co-founder). By figurehead, I mean the person who drives the community, posts regularly on their personal blog (or other outlet) and on the business blog, and who is generally visible. Of course, we all know of founders who have got terrible reputations and who are still extremely successful. But there’s no way of telling how much more successful they would be if they weren’t perceived to be such assholes.

There are quite a few WordPress founders who are doing it really well – particularly notable are Brian Gardner of StudioPress, and Dre Armeda, of Sucuri. Something notable about both of them is that they both have one thing that people associate them with – for Brian it’s Starbucks, and for Dre it’s tacos. Knowing Dre personally, I know that he’s much more than a guy who likes tacos – but they’re on to something pretty smart.

The online medium seriously limits our ability to communicate. Online, people don’t catch the nuances of your personality. If you’re a dick, you’re a dick. No one is going to know that you’re a great parent, or that you’re passionate, or that you’re lovely to your staff. Whatever you do online, your identity is limited, and it’s up to you to ensure that you choose the limits and that they’re positive. Communication online is restricted, and the people most successful at creating an online persona get that. They choose what they want people to associate them with. A few ill chosen words, or snarky comments, can totally transform how people perceive you, even if you were just having a bad day. Create your online persona, make it likeable. And remember, it’s not really you.

Learning

I wrote a few weeks back about using an agile approach to documentation in WordPress. This means keeping your documentation lightweight so that it a) provides everything your user needs to get set up, and b) is easy for you to update. You blog is an important tool when it comes to providing users with additional learning that will help them to make the most of your product. This is less about showing off your knowledge, and more about an additional layer of documentation for your user (though sometimes these merge. Some examples of suggestions I would make to different businesses:

• Theme Shop – tweaking a theme’s CSS, choosing fonts, working with layouts, plugins that enhance the theme, working with advanced options.
• Plugin developer – use cases for setting up your plugin, customizing your plugin, making use of hooks, complementary plugins and add-ons.
• Hosting company – relevant version control systems, deployments, advanced performance tweaks and techniques.

Conclusion

That was longer than I intended it to be….. but, hopefully it was useful. They’re just some of the things I look for when helping a WordPress business come up with a strategy for its blog. One of the most important things, which I haven’t talked about, is doing research. A lot of the solutions I come up with will be based on research into a) how you want your product to be perceived, and b) what your community and customers want/need. Maybe I’ll talk about that another day!

But if you take away just one thing from this, remember to do some planning before you start blogging. And don’t get SEO companies to churn out articles for you!

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.

Add value

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

Resources

• Agile/Lean Documentation: Strategies for Agile Software Development
• Best Practices for Agile/Lean Documentation

In the meantime, check out the website. There are a few Easter eggs scattered about the place. The beautiful new design was done by Tammie Lister at Logical Binary, and the illustration on my About page was done by Rachael Smith.