Support Everything WordPress

Updates from November, 2012 Toggle Comment Threads | Keyboard Shortcuts

  • Siobhan 12:48 pm on November 16, 2012 Permalink  

    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.


    Here’s who we’ve got so far:

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


    Daniel Bachuber
    Japh Thomson

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

    Plugin 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 🙁 )


    Brandon Dove
    Ryan Imel
    Aaron Jorbin
    Sara Rosso

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


    Zé Fontainhas


    Andrea Rennick
    Christine Rondeau
    Dean Robinson

    These things span all of the handbooks:

    General help

    Kari Leigh Marucchi
    Abbie Sanderson

    Shane Pearlman
    @helenyhou or other person from UI
    Mel Choyce


    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.


    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.


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

    Useful tools to get started

    The different ways that you can get involved in this area

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

    Glossaries etc (maybe useful email addresses etc?)

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

    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 Github 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 Permalink
    Tags: 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:


    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?


    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.

    • Japh 1:57 pm on December 6, 2012 Permalink | Log in to Reply

      I know we’ve talked about this in person, Siobhan, but I just wanted to put down here that I’m happy to be involved in the handbooks for Core and Plugin Development 🙂

    • jhoffm34 3:39 pm on November 9, 2012 Permalink | Log in to Reply

      I’m a total newcomer but I would love to help out with the theme development or mobile handbook. It’s what I generally work on in my professional life and I’ve been looking for ways to give back.

    • karmatosed 5:48 pm on November 5, 2012 Permalink | Log in to Reply

      I’d like to help from a theme designer/dev perspective. I could also help from UI side too if needed.

    • Chris 5:43 pm on November 5, 2012 Permalink | Log in to Reply

      I’d be interested in helping out with the theme development handbook.

    • Sara Rosso 5:34 pm on November 5, 2012 Permalink | Log in to Reply

      I’d like to help with documentation! Events and New Users would be good ones for me to tackle.

      One thing that’s not clear is how the New User info will be funneled back / synced back with up the Codex? Feels like a lot of overlap.

    • Helen Hou-Sandi 4:56 pm on November 2, 2012 Permalink | Log in to Reply

      Thanks for the awesome summary/update! UI is a funny thing because different parts end up in different areas – what we do for core vs. best practices for plugins/themes, that sort of thing. I think it’s better off as an integrated portion of each so that it is considered an integral part of the whole, rather than secondary and separated as it is sometimes considered by those who don’t value it as much.

      • Ipstenu (Mika Epstein) 5:55 pm on November 2, 2012 Permalink | Log in to Reply

        At the very least, I think UI can encourage people to not do silly things like reinvent the wheel with their own buttons 😉 If you think it’d be better to have like a two-page ‘UI for Plugins’ and ‘UI for themes’ and then ‘UI for FrontEnd – how not to piss off your users’ though, we could write them on their own and integrate?

        • Siobhan 8:50 pm on November 2, 2012 Permalink | Log in to Reply

          A UI section for each manual that involves development would be great. Would love to have some of the UI guys helps out with that.

    • Kari Leigh Marucchi 9:26 pm on November 1, 2012 Permalink | Log in to Reply

      Would like to help. I’m the client procedure documentation specialist for our company. So I’ll review the needs and see if I think I can fill any gaps and will get back to you. Great to see this going on!

      • Siobhan 3:09 am on November 2, 2012 Permalink | Log in to Reply

        We’d love to have you on board – am sure your expertise would be a great addition. Once I’ve collected volunteers I’ll post something about the next steps.

    • Lee 9:03 pm on November 1, 2012 Permalink | Log in to Reply

      Hi Siobhan,

      Unless it’s covered anywhere else – do you need an “Accessibility” handbook ?

      • Siobhan 9:05 pm on November 1, 2012 Permalink | Log in to Reply

        Yes! I knew that I’d forget something. I’ll check with the the team rep to see if they want one (not sure who’s leading accessibility tho)

        • esmi 11:06 am on November 2, 2012 Permalink | Log in to Reply

          • Siobhan 5:13 pm on November 2, 2012 Permalink | Log in to Reply

            Excellent. Would you like to have a dedicated accessibility handbook, or would you prefer to see accessbility as a part of plugins/themes/core?

            • esmi 8:38 pm on November 2, 2012 Permalink | Log in to Reply

              The latter. Accessibility is too big and goes well beyond WP’s remit, so I think it’s better for us to focus on what we can do to help/support the other areas of development.

            • Siobhan 8:43 pm on November 2, 2012 Permalink | Log in to Reply

              I think that’s the best approach too. Accessibility guidelines for each development manual. Can you help us to get those right?

            • esmi 1:56 pm on November 5, 2012 Permalink | Log in to Reply

              Just point me towards the places that these guidelines would be useful and I’m sure we’ll be able to put together something suitable.

    • JerrySarcastic 6:31 pm on November 1, 2012 Permalink | Log in to Reply

      Siobhan, I have already started a little wireframing on my own; when you get Balsalmiq set up, I’m happy to contribute.

    • Siobhan 5:05 pm on November 1, 2012 Permalink | Log in to Reply

      P.S. @vanillalounge has volunteered for the polyglots handbook 🙂

    • Brandon Dove 4:51 pm on November 1, 2012 Permalink | Log in to Reply

      We’ve already got some traction going on the Events handbook here: https://gist.github.com/3955569. For the sake of consistency, should we move http://plan.wordcamp.org to http://make.wordcamp.org/events/handbook?

    • Amy Hendrix (sabreuse) 3:04 pm on November 1, 2012 Permalink | Log in to Reply

      Exciting stuff! Thanks for keeping it all moving!

    • christine 2:59 pm on November 1, 2012 Permalink | Log in to Reply

      I thought that the handbooks were being moved to learn.wordpress.org ( see Mika’s last post – https://make.wordpress.org/support/2012/10/summit-action-items/ )

      Also, the new section for Teachers might have a lot of overlap with Theme Development. We’ll have to coordinate and make sure we don’t just simply repeat ourselves.

      I won’t be incorporating anything about plugins, though. As a teacher, I never teach that part and Brad Williams will be 1000% than I for that part.

    • Brad Williams 2:55 pm on November 1, 2012 Permalink | Log in to Reply

      I’m really excited to see this starting to take shape! I am definitely in to help with the Plugin Development handbook. I also have a lot of experience laying out sections/sub-sections so could contribute to the overall structure of the handbook as well.

      • Pippin Williamson 3:05 pm on November 1, 2012 Permalink | Log in to Reply

        I’d be happy to help with the plugin dev handbook as well.

        • Siobhan 3:29 pm on November 1, 2012 Permalink | Log in to Reply

          Sweet! Looks like we’ve got a plugin dev handbook team shaping up.

          • Brad Williams 5:00 pm on November 1, 2012 Permalink | Log in to Reply

            What are the next steps as a team is formed? Should we track who is in each team somewhere or are you handling that Siobhan?

            • Siobhan 5:05 pm on November 1, 2012 Permalink | Log in to Reply

              Let’s gather volunteers over the next few days or so. Once I get most of the bases covered we could have a Google hangout to start fleshing things out. I was thinking that if we form small teams for each handbook, each with an editor and a group of authors, that may be a good way to approach it.

              Once we’ve discussed workflow etc we could look at a task management app like Trello or Asana for managing the whole thing. I’m totally open to suggestions though. So once we’ve got our volunteers let’s get into a hangout and talk it out.

        • Maor Chasen 7:38 pm on November 5, 2012 Permalink | Log in to Reply

          Same here. Would love to help with that.

      • Dougal Campbell 4:16 pm on November 1, 2012 Permalink | Log in to Reply

        As I mentioned at WPCS, I see a big black documentation hole where Best Practices should be. So I will start bringing some resources together on that. I’ll start with plugin dev / security topics, but there’s a lot of overlap with themes, so I’ll be dipping into that, as well. Not sure what kind of time I’ll have, but I’ll make time. “I will!” 🙂

        • Siobhan 4:53 pm on November 1, 2012 Permalink | Log in to Reply

          Cool. I think every handbook should have a Best Practices section. That’ll be a great resource for people to learn, and to point to people to when they’re doing things wrong.

      • Tom McFarlin 6:20 pm on November 14, 2012 Permalink | Log in to Reply

        If it’s not too crowded, consider me on board for the Plugin Development handbook, as well.

compose new post
next post/next comment
previous post/previous comment
show/hide comments
go to top
go to login
show/hide help
shift + esc
Skip to toolbar