Archives

Siobhan 12:48 pm on November 16, 2012  

Handbooks: Teams and Templates

Over the past few weeks I’ve been getting in touch with people who I’d like to see involved with the handbooks. I’m going to continue to do this over the next few weeks as we get started on working. I just wanted to give you an update on teams and templates.

Teams

Here’s who we’ve got so far:

[update: am adding more people to teams as they contact me]

CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.

Daniel Bachuber
Japh Thomson

Support
Andrea Rennick
Scott Basgaard
Christine Rondeau
Dean Robinson
Phil Erb
Mika Epstein

PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party Dev
Pippin Williamson
Dougal Campbell
Tom McFarlin
Thomas Griffin
Maor Chasen
Justin Sainton

Theme Dev
Chris Reynolds
Tammie Lister
Rachel Baker
Jay Hoffman

Theme Review
(no one so far 🙁 )

Events

Brandon Dove
Ryan Imel
Aaron Jorbin
Sara Rosso

Mobile
(no one so far 🙁 ) Except Isaac?
Abhishek Ghosh

Polyglots

Zé Fontainhas

Docs

Andrea Rennick
Christine Rondeau
Dean Robinson
Me!

These things span all of the handbooks:

General help

Kari Leigh Marucchi
Abbie Sanderson

UXUX UX is an acronym for User Experience - the way the user uses the UI. Think ‘what they are doing’ and less about how they do it./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.
Shane Pearlman
@helenyhou or other person from UI
Mel Choyce

AccessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility)
Esmi

We definitely need more people so if you know of anyone please send them this post. Or drop me an email: siobhan at wordsforwp dot com and I’ll get in touch with them personally.

Template

After having chats with different people in different contributor groups and reviewing the material that we have already, I’ve come up with a very loose schema that I think will work across the handbooks.

Introduction

Requirements
All of the things you need to start contributing to this area

Tools
Useful tools to get started

Pathways
The different ways that you can get involved in this area

Tutorials & Guides
Practical guides to doing what you need to do

Reference
Glossaries etc (maybe useful email addresses etc?)

Best Practice
Coding Standards, Best Practices, UI Guidelines, UX Guidelines, Accessibility

Credits
Lists the contributors to that manual.

This is a starting point, so please do make suggestions based on your own experience. There’s always a danger when you’re creating something generic that you lose the specific, which is why I’ve tried to keep the schema as loose as possible.

Some other things

I have a chat with Brad and Pippin about the plugin development handbook. They had some great ideas to keep in mind:

  1. We should use practical examples of code that will help people to learn
  2. We need a syntax highlighter of some description. We did discuss using Gists but then our docs are reliant on GithubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ and that not something we want

I think there may have been other things so Brad and Pippin if I’ve forgotten something please chime in. Soon we’ll get into discussions about the particularities of specific handbooks I’m sure, but I wanted to note these here for the record

Next Steps?

Next steps are as follows:

  1. Come up with schedule and workflow – I’ve got some stuff written down on this but will save for another post! Let’s aim for long term – we don’t want to burn ourselves out.
  2. Schedule some google hangouts with contributor groups and volunteers to discuss best practices
  3. Develop table of contents

Okay, phew! That was a long post again. Let me know if I’ve missed anything, please do add any suggestions or tell me where things can be improved.

Most importantly, spread the word. This is an exciting project in its beginning stages and over the next year we’ll be able to create something we’re genuinely proud of and that gets more people contributing to WordPress.

Siobhan 2:48 pm on November 1, 2012
Tags: handbooks   

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