Upgrade your client services with documentation

Upgrade your client services with documentation

Curtis defends that including solid and comprehensive documentation with your projects is probably a task you can no longer ignore, if you want to stand out as a more complete WordPress developer.

When I started building WordPress sites I actually thought my job was done once I handed off the site to the client; the code is written, it is theirs now. I suppose that worked: I was able to pay my bills, but didn’t see many of those clients again.

Then I started providing some documentation and training for clients. Yes, it was a bit of a pain, but curiously enough they kept coming back for more work, and not just more training work, also development work.

I firmly believe that upping my game by providing training and documentation is the reason clients started coming back. Expanding my level of service created a great way for me to earn more, both with my hourly rate and also by having more items to charge for.

How to Document

The backbone of any solid documentation, for me, is to have it appear where the client can easily find it. I always use WP Help by Mark Jaquith to add documentation to client sites.

WP Help filled with content for a client

WP Help filled with content for a client

Once the client can find it, we need to remember a few other things:

First, our clients aren’t developers, there are many items that we take for granted which they simply don’t know. Take shortcode parameters, for instance; they may seem easy to us, but to the vast majority of clients shortcodes are simply code and look odd.

Secondly, many of your clients may not have any idea of what WordPress is. Telling them that they can change the menus doesn’t tell them that the menus are located under the Appearance menu in the WordPress admin. They may never find it, or just spend a bunch of time and be frustrated with how ‘bad’ WordPress is, even if they do find it.

When writing documentation for users, you need to assume that they have no idea where anything is. Provide twice as many screenshots as you think you need, and twice as many explanation steps. Don’t assume anything.

The ‘over documentation’ point was brought home to me with a recent client, whom I had provided with a site built on WordPress and WooCommerce. All of the staff adding content to the site had used WordPress before. We had been running a local kayaking blog together for years, but when it came to the higher level admin stuff, like changing menus, they had absolutely no clue. I started with less steps which resulted in getting calls to clarify. As soon I doubled the steps and screenshots, I got emails about how awesome the documentation was.

What to Document

Should you provide documentation for all of WordPress, or just for the items that are custom to your client’s site? By default, I write documentation for any of the custom stuff and not for all of WordPress. That premium service is what allows a premium price.

But what if your client is 100% new to WordPress? What if they do need total WordPress documentation? Should you write it all yourself, or find it somewhere else?

A great place to point your client is the Working with WordPress section on the Codex. There you can find lots of information on how to use WordPress. Another great thing about the Codex is that the documentation is kept up to date by the community. You don’t have to check back in on client projects to make sure their documentation is up to date with the current changes in WordPress.

Once you have a great series of basic WordPress tutorials, you only have to provide documentation for any of the custom items. Make sure you cover subjects like how to set up the home page slideshow, how to use shortcodes, how to add or remove the social links on the site, and anything and everything that wouldn’t be covered in a basic ‘how to’ WordPress tutorial.

What Type of Content

So far, we’ve talked about written content on your custom documentation. While it is a good start, it’s certainly not all there is to it. There are many learning styles, and trying to accomodate them may create the need for other types of content: WP101 and Lynda are not going to be able to provide screencasts for your custom development work.

I always include a screencast on how to use the custom shortcodes, and even make sure I provide a link to the page on the site that uses it; not only does that show the user how to use their own custom shortcodes, it also shows them how to use shortcodes in general. You can see an example shortcode screencast I’ve provided to a client, below.

I use Screenflow to record and edit my screencasts. A great Windows option is Camtasia.

Learning to record screencasts and all that editing is a big job though. If you don’t want to learn that you still have a few options to provide screencast documentation for your clients.

WordPress.tv is a great place to start, specifically the how to category. You can find tons of videos that are applicable to your clients’ training needs, which can be included directly in your WP Help documentation.

If you don’t want to spend the time curating the basic training materials, you can always include a membership to a service like WP101 or Lynda. Yes, it costs you a bit, but then again so does the time you spend finding great tutorials. Providing these to your clients is a huge value addition, in the eyes of clients.

It’s important to note here that I don’t think screencasts stand totally on their own. Some people simply don’t learn by watching a screencast and you’ll need to provide both written and screencast documentation.

If your project is large enough, you can use a system like Flatdoc or Beautiful docs.

Flatdoc allows you to write markdown documentation

Flatdoc allows you to write markdown documentation

Either option allows you create a complete documentation site for a client, based on markdown. The resulting site will not be built in to the WordPress dashboard, but having a separate site also allows you to have a repository of not only your documentation, but also of business processes, branding and print, and more, which probably wouldn’t really make sense in the WordPress dashboard.

I hope that I’ve managend to convince you that simply writing code for a client is but a small part of the service you cloud be offering. Tying the whole project up with a full set of documentation is a great way to provide more value for a client, which in turn means that you can charge more, and more often, for your services.

It’s not just about the money. Providing documentation for your development work will not only make your professional services stand out above most, but also your client will love how empowered they are with their site.


  1. says

    This is excellent advice. I find people can usually work out basic functionality, but as soon as you add custom stuff in there with lots of post types, featured images, post meta etc. then it can get really complicated fast. Documentation is critically important when it isn’t obvious how to update the site.

    • says

      I agree, but I still have clients that have trouble tackling the basics. I think it’s either due to being lazy and not wanting to put in the effort, everyone expect everything handed to them. It drives me crazy sometimes. Documentation is very critical though and like you mentioned things can definitely get complicated fast when there’s a lot of custom functionality and design.

      • says

        Using WP 101 (or a similar service) can cover the basics for your clients. It’s not super hard to include in your basic services at all.

      • says

        IMO, the fear of homework never leaves us, even when we grow up. Someone tells you to go read some articles or watch a series of videos? You need to be motivated to do that. And I don’t think the motivation is there for a lot of our clients. It’s just another task to go on their to-do list.

        I think that’s the problem with centralized resources as a whole, no matter their quality. You have to read or watch something and then relate what you’ve learned to whatever you’re trying to accomplish. Compare that to having someone leaning over your shoulder and walking you through things step-by-step.

        This is the market that sites like Codecademy and Treehouse and Code School are tapping into. It’s all interactive. Minimal studying. You learn by doing. (That’s actually what got us started on building a training plugin. Less repeat work for devs, more useful for clients.)

        TL;DR = Documentation and resources are good, but not a replacement for hand-holding. We’re trying to hit a middle ground. It’s not easy. But it gives our clients a better experience.

  2. says

    I use WP Help and screen casts for all of my documentation. I try to keep them as short as possible and to the point. What I haven’t done yet is make some of these screen casts usable for all of my clients so that I don’t have to repeat work. I also found that doing training after handing the site off is a bit overwhelming for them… so I’ve started doing training with only fundamental things like adding and editing posts, pages, and images… then they can learn the rest with the videos.

    • says

      I’ve taken some of my screencasts and made them generic and even put them on YouTube as a secondary revenue stream. I did one for adding variations on products in WooCommerce and that gets a bunch of traffic. My clients get an ad free version I host elsewhere but the $10/month on Youtube is still $10 that ads to my bottom line.

  3. says

    Interestingly enough, we just started talking about providing a PDF User Guide document with all of our client projects. We already do this for our premium products and it makes sense to do the same for clients.

    I did not know about the WP Help plugin and will be looking into this because a separate PDF document just feels problematic and I like the idea of documentation being available in the dashboard.

  4. says

    Thanks for the mention, Curtis. And alongside Lynda, no less! :)

    Providing custom documentation is a critical step in handing a site over a client, and Mark’s excellent WP Help plugin fits the bill nicely.

    In fact, it’s why we reached out to Mark to have him code our own WP101 Plugin, which not only provides a complete set of our own basic WordPress tutorial videos right in the dashboard, but also enables developers to easily add their own custom videos.

    I agree completely that video tutorials aren’t for everyone, and providing both written and visual documentation is ideal. But often, it takes much less time for a developer to quickly record a 3-minute screencast to demonstrate the custom features specific to a client’s site than to write out detailed, step-by-step instructions. That’s where the WP101 Plugin proves itself handy.

    Great article, and thorough explanation of the various options out there. Thanks again!

  5. says

    Thanks for the great article, Curtis. I too feel that the training process is a very important aspect of client services and shouldn’t be overlooked. And furthermore, I felt that the training process should be simplified and automated.

    I’ve been working on Client Instructor, a web-based tool for this exact kind of thing and would love for you to try it out. The great thing is that it isn’t just tailored for WordPress, but for Joomla and Drupal as well. And you can easily create your own templates for proprietary software or custom CMS’s. It will create a web-based instruction manual that you can send to your client, with easy ways to download as a PDF or print.

    Our WordPress plugin will allow you to integrate these instructions to your client’s dashboard, and you can manage it completely through our interface. It will keep you organized and speed up the process in which you train your clients. And it isn’t limited to one platform (we’re interested in adding other popular platforms such as Google Analytics, and even SEO and Social Media). Check it out and let me know what you think!


Leave a Reply