IRC Recap – Nov 1

DST messed us all up.

Teams: Pick One

When we start getting our groups sorted out, pick one. Part of our burnouts happen when we’re spread too thin, so pick one thing and run with it. If you do videos, do videos. You can help out here and there with the others, btu let that be your main focus 🙂 Once we all settle back in from traveling, we’ll sort out how we want to collect and direct our teams.

Rotating IRC

Since we can’t hit everyone, I’m thinking maybe we should start moving the times around so some days work better for others, etc etc. If everyone who wants to be in IRC can post their best times, I’ll come up with some rotating schedule for IRC chats, so everyone can get in.

Roadmap for Documentation

Andrea and Siobhan are going to sort out what needs to be Handbooked and what needs to remain codex’d. There’s a Wiki tag of <code>{{Handbook}}</code> that will start being slapped on pages we think should be brought into Handbooks. Many pages, like the functions etc, will stay as they are, as will info on permalinks. We need to discuss (on wp-docs) this roadmap at a high level, before we can get into the nitty gritty.Look for that 🙂

By the way, people have asked about Videos. The short version is “Are you interested?” I will be taking names and coordinating with Andrea M. to sort out how to get you other to WP TV 🙂 Just have to work with Andrea M, so she’s not overwhelmed! There will be a Video Post for you to toss your name in that hat.

User Guide

This has been copy-edited (yay! Thank you Christine) so the next round is ‘Pull in images from .com’ Whenever possible, just download the image from .com and upload. When not? Yes, we need a new screenshot. There are also some pages where we’re not 3.5’d yet, so feel free to tweak as you go. The Guide may not get a home until post 3.5, depending on how much time the .org server people have.

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:

  • CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.
  • 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 UIUI UI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing. 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:

  • Core – https://make.wordpress.org/core/handbook/
  • Support – https://make.wordpress.org/support/handbook/
  • Docs – https://make.wordpress.org/support/doc-handbook/
  • New Users – https://make.wordpress.org/support/user-manual/
  • Polyglots – https://make.wordpress.org/polyglots/handbook/
  • Theme Review – https://make.wordpress.org/themes/ (see pages nav) Also, https://codex.wordpress.org/Theme_Review
  • Developing Themes – https://codex.wordpress.org/Theme_Development
  • Developing Plugins – https://codex.wordpress.org/Writing_a_Plugin
  • Events – http://plan.wordcamp.org/

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.

#handbooks