How To Document WordPress Projects

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

Manual

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?

15 Comments

When learning something new I like to use a mix of different techniques. I might watch a short intro video just to get an idea, then I’d like to see a few short and to the point examples demonstrating a few essential features.
When I’ve grasped the basics, I’ll come back and want to find more in depth guides or documentation and some sort of reference that I can navigate quickly.
But definitely, nothing should be longwinded, but short, concise and to the point wins every time.

    Yeah – think this goes to show that we all have different learning styles. Once we discover them, I think that it helps us to move faster in learning new things.

    The problem is that, as developers, we have (well, should) to produce documentation that caters to all of those styles.

    And though that can be challenging, I think that you’re that the more concise and direct it can be, the more beneficial to all who are involved.

One of the primary objectives behind building my Opus Primus theme was documentation. To that end, I made it a priority to use extensive PHPDoc style documentation throughout the code, as well as a great deal of inline code comments.

I also chose to register a domain specifically for the theme where end-users can not only see it used in a live environment but also read post and pages specifically and exclusively written about the theme.

Video tutorials and a manual may be down the road but there are no specific plans for them, yet.

    To that end, I made it a priority to use extensive PHPDoc style documentation throughout the code, as well as a great deal of inline code comments.

    Love this – this is something I’ve begun doing in the past year or so. I’ve always been a fan of code comments, but I’ve never actually followed true PHPDoc conventions (and generating said documentation) really until within the last year.

    I also chose to register a domain specifically for the theme where end-users can not only see it used in a live environment but also read post and pages specifically and exclusively written about the theme.

    I used to do this with my premium plugins before I killed them off, but we do something similar to this at 8BIT with our documentation. Right now, it lives on our main domain – and there are reasons for that – but we really only have a single digital product that requires a manual.

    For now, at least.

    Video tutorials and a manual may be down the road but there are no specific plans for them, yet.

    Have you happened to have had demand for either, yet?

The video tutorials for Canvas at Woothemes are excelent. Note they are out of date, but it is striking that they give you a quick general idea of what Canvas was made for and how you get excellent results quickly.

Pont to take home: It is utmost important to first communicate the general philosophy.

Apple is an other great example. GUI is utmost important, it is what users see first and work most with. (not your code or your documentation of it) Not only put your time in decant coding. But ideally, first workout the user interface. It should be clear, clever and easy to understand from the user point of view. Descant and clever GUI that explains it self, is what fails most often in the WordPress world.

As coder find a GUI specialist to work with

    It is striking that they give you a quick general idea of what Canvas was made for and how you get excellent results quickly.

    I think that’s the mark of good documentation: quick ideas quickly.

    Apple is an other great example.

    Yes, yes. This is exactly why I pulled in:

    Insert coin
    Avoid klingons

    It’s very hard to achieve that elegance and I think we’re at a point in software and applications where people are too liberal with throwing the word “elegant” around. I’ll be the first to admit that I think Apple’s made some missteps in the GUI department, but that doesn’t mean they’ve failed.

    They’re still my favorite devices – and I’m not starting a fanboy discussion (because I’m not one) – because their usability does trump many of their competitors.

I have to confess I learn by doing it and asking other people, I will on occasion RTFM, but for the most part I play, break it, fix it, break it again and fix it again.

I’m not pretending this is the most efficient process, but I won’t lie, I enjoy this way of doing it over getting stuck reading, or watching video… for some obscure reason that just feels like wasted time…

    I have to confess I learn by doing it and asking other people, I will on occasion RTFM, but for the most part I play, break it, fix it, break it again and fix it again.

    This is generally how I learn to – the short of it is that I learn by doing and less by reading, and this is really how it’s always been for me (through school, in hobbies, etc).

    That’s not to discount reading – I still do it – but it’s not as effective for me as doing it.

    I’m not pretending this is the most efficient process, but I won’t lie, I enjoy this way of doing it over getting stuck reading, or watching video… for some obscure reason that just feels like wasted time…

    I completely get what you’re saying. I don’t necessarily find it a waste of time, but I find it as a lack of productivity – though I’m learning how to do something, I feel that it’s not fast enough. I’d rather be doing something active (or tangible – however you want to define it) .

    Plus, I’m impatient. So there’s that, too ;).

I’ve made short videos for a number of projects I’ve built. I think new users to WordPress find these especially helpful. They don’t necessarily know where the “Widgets” menu is, or the “Screen Options” tab- so being able to see that on the screen is really great.

One potential downside is that you’ll need to re-record these every couple versions of WordPress as the UI changes, etc- but that is also an opportunity to revisit your documentation and make sure it is completely up to date.

    For videos, I’ve done something similar – I’ve had to explain to customers, though, that if they want WordPress updated and will want the documentation associated with it to be updated that it’ll be an additional cost.

    Normally, this is only done when I have projects that have a unique set of custom post types, meta boxes, etc.

    One people get over the initial learning curve of WordPress, they seem to do okay with upgrades assuming that they’re spending time in the dashboard every day or so.

One of the things that I always found difficult when creating WordPress themes for clients, was working out how to train them. When you work with interstate clients it obviously makes it hard to provide any personal one-on-one type training and sending them a bunch of links to different websites or articles is pretty much useless as you just know they’ll never look at them.

When I first started working with WordPress years ago, I was also a bit frustrated that there wasn’t any “manual” to go along with it. There’s heaps of information in the Codex, but it can be pretty daunting to a new user, or a client, especially one that isn’t all that familiar with Content Management type systems.

In the end, I ended up writing my own WordPress manual. My aim was to write something that was easy to read and that covered the basics in regards to editing & updating your site content. My intent wasn’t to cover setting up the site or editing theme files. There’s plenty of information on those topics within the WordPress Codex and on the web, if that’s what they’re after.

I know a lot of other freelance developers who are in a similar situation, so I decided to release my manual under Creative Commons in the hope that it helps other designers/developers in the WordPress community. I’ve been updating it for the last couple of years – http://easywpguide.com

    When you work with interstate clients it obviously makes it hard to provide any personal one-on-one type training and sending them a bunch of links to different websites or articles is pretty much useless as you just know they’ll never look at them.

    I’ve tried everything from screencasts to screenshots and even walking throughs via images and documentation.

    My overall take away is simply that it varies from client-to-client. There’s no universal solution. Knowing that makes it a bit easier to provide a clearer estimation on the front end (but that’s a whole other post ;).

    I know a lot of other freelance developers who are in a similar situation, so I decided to release my manual under Creative Commons in the hope that it helps other designers/developers in the WordPress community. I’ve been updating it for the last couple of years – http://easywpguide.com

    Now this is cool. Definitely bookmarking and will likely be using it for future projects. I’ll aim to promote this too either here or on WP Daily to get it more exposure!

Atari never had a Star Trek arcade game or any game with those instructions. Isaacson didn’t fact check that properly.

    Thanks for pointing this out – went and researched that myself after your comment. Who knew.

    Regardless, the point still stands, in my opinion, whether or not the accuracy of the quote is correct, you know?

Leave a Reply

Name and email address are required. Your email address will not be published.

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>