Earlier this week, I wrote about the challenges of documenting WordPress projects regardless of if they are free or premium.

In the post, I mentioned that another challenge that comes with actually documenting a project is making sure that you’re catering to the various ways that people learn.

First, as a general rule, I think that projects should include:

  • Source Code Documentation. Free projects should have code comments, premium projects should have code comments, PHPDoc (or similar) style documentation, and API documentation if one is available.
  • A Manual. Free projects should have a README and potentially a web page, premium projets should have a manual that’s perhaps its own website complete with screenshots and/or videos.

But this raises a second question about WordPress documentation, specifically around premium projects: If people have different styles of learning, that is, some learn better by reading, others better by watching, are we obligated to provide both forms of documentation?

The Best Way To Document WordPress Projects

Honestly, I have no idea. I’m someone that generally dislikes videos because I feel that I can grok the information faster by reading it, and it usually takes much less time.

But that’s me.

Others would rather see someone walk them through the process of setting up a piece of software so that they can follow along while doing it. Additionally, this allows them to write down questions they have to submit to support should the need arise.

Written Manuals


An epic plugin manual

To me, the main problem with written manuals isn’t so much that people can’t learn by reading – I believe that even if you learn better by watching a video, a well-written manual with screenshots can be effective, but I wonder if people are willing to read.

We live in an age in which people generally scan the articles on the web. Why would a manual be any different?

Video Guides

Video Manual

Even better – video manuals!

In contrast, video guides can be highly effective, but I don’t think that people are usually willing to sit and watch a 10 – 12 (or longer) video on how to use a product.

Instead, they’d rather have the videos broken down by topic or by ‘how to achieve a certain task,’ and accomplished in three to maybe five minutes.

But, from a developer’s standpoint, this becomes a challenge because, let’s face it, most developer-types are not video producers, so if you want to out source that work, you still have to work with someone (or some team) to produce the video and make sure they understand how to use your work.

Why Usability Matters

All this to say is that documentation – a natural part of the software development lifecycle – is not easy especially if you want your customers’ experience to be as pleasant as possible.

But there’s one more factor that goes into knowing how to use a product: Usability. I remember when reading Steve Jobs, one of his goals for the first Macintosh was that it should be as simple to use as the Star Trek Atari video game.

Steve Jobs and Steve Wozniak

Simply put, he wanted to develop the system so that figuring out how to use it followed suit of the Star Trek manual:

  1. Insert coin
  2. Avoid Klingons

Say way you will about developing software, user interfaces, accessibility, Steve Jobs, hardware, software, or whatever, but I still think this is an excellent goal to which all product developers should strive.

To that point, I’m not arguing against code comments – because I think they are useful – and I’m not arguing against writing against documentation – obviously – but I’m trying to strike a balance between all of the things that go into making a product.

And usability is a major factor in how well users can get up and going with your work.

What Documentation is Best?

Finally, what form of documentation have you guys found the be the most effective?

I’m shameless in asking because I’d rather borrow ideas from what the rest of you have learned rather than jump into this blind and have to do a lot of guesswork :).

So … thoughts?