Handbooks!

Hi everyone,

We had a really productive chat about the WordPress Handbooks over the weekend, and I’d love to see a push on them. It’ll be a long term thing, no doubt. The aim of the handbooks is to provide useful guides and references for people who want to contribute to WordPress. You can already see an example of the beginnings of one on the WordPress Core Contributor P2.

The handbooks will be:

  • Core
  • Support
  • Documentation
  • Polyglots
  • Mobile
  • Theme Review
  • Developing WordPress Themes (in adherence to the theme review guidelines)
  • Developing Plugins for the repo
  • Events

Tell me if I’ve missed anything!

I don’t think Systems need a manual. I spoke to @helenyhou and for now UI will be part of core. If, as the content progresses, the UI guys feel that they need a handbook we can help them to put that together.

I’d love it for the handbooks to be written as a collaboration between the support/docs team and the various contributor groups. That means corralling people from across the community to get involved. There’s already a lot of content that we can work with, and we can create more. Here are some resources for finding the current documentation:

Structure

At the summit we discussed creating these as a set of educational resources for contributing to WordPress. Rather than just diving in and creating a whole bunch of content I think the approach to take is to start off with a schematic structure. It would be great to start off with the intention of creating a set of documentation that is coherent – kind of like a set of Cliff Notes books that you get for studying at school. This means that if someone has become familiar with one handbook they’ll be familiar with the structure of the next. This is a great aid to learning. To achieve this, we could do the following:

  • come up with a schematic content template that will be used for each of the handbooks. This will have to be done by looking at all of the content that we think we’ll need and building up the content template from that. It shouldn’t be too prescriptive as every group has its own needs, but an underlying structure
  • use a schematic template for individual doc items.
  • use the same tone of voice and language across the docs.
  • use coherent styles for different elements in the docs. For example, having call out boxes that have the same styles for tips, or other important information.

Every guide will include best practices.

Anything else that anyone thinks that would help to achieve consistency?

Content

Once we have a structure then we can start to think about content. I’ve had a number of people say that they would like to get involved with this project, particularly with events and plugins. If anyone else would like to help then leave a message in the comments.

Ideally, we should divide the workload as much as possible. We should also make best use of everyone’s expertise. I was thinking that we could create a workflow that went something along these lines:

1. Volunteer from contributor group produces the content. If the person is unable to create the content themselves, this could be a recommendation for what they want, or a link to a blog post or another article that has the information required. This doesn’t need to adhere to the voice and style guidelines.
2. Volunteer from the doc team edits the content to get it into house style, make sure everything is clear, and add any content as needed.

What next?

First steps:

  • gather volunteers from the various contributor groups, or from people who are working in the different areas who would like to be involved.
  • get suggestions about the content that should be included in the handbook.

Second steps:

  • come up with some mockups of how users can navigate and use the documentation. I can start a project in Balsamiq and we can collaborate using that.
  • come up with the content structure
  • develop a workflow to ensure that:

a) things get done
b) we keep on top of updates

Third steps:

  • write, bother people, nag, edit

Final step:

  • drink beer

I read a great quote when I was doing some research on docs for a client. It said ” User documentation should be considered part of the user interface for your system and therefore should undergo usability testing.”

I’m not sure if we need to concern ourselves with usability testing (though we may want to in the future) but we should keep clarity, usability, and user experience in mind at all times throughout the process. We want awesome handbooks that are useful and that help us to grow the contribution community.

Phew – that was a lot! They’re all the things on my mind right now but let’s have a discussion.