Supporting Everything WordPress

Updates from November, 2012 Toggle Comment Threads | Keyboard Shortcuts

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

    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]

    Core

    Daniel Bachuber
    Japh Thomson

    Support
    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 :( )

    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

    UX/UI
    Shane Pearlman
    @helenyhou or other person from UI
    Mel Choyce

    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 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 12:54 pm on November 16, 2012 Permalink | Reply

      Note to self: handbook translation. Bother @vanillalounge :D

      • mrmist 7:59 am on November 18, 2012 Permalink | Reply

        I should really help out with Support and probably Docs.

    • toscho 1:07 pm on November 16, 2012 Permalink | Reply

      What would be the content of Support?

      • Brian 1:09 pm on November 16, 2012 Permalink | Reply

        Curious as well.

        • Siobhan 1:43 pm on November 16, 2012 Permalink | Reply

          Support already has the beginnings of a handbook here: http://make.wordpress.org/support/handbook/

          I guess it would include things like:

          Requirements – what you need to get started – level of knowledge. Encourage people to help answer questions even if they feel that they are still beginners.

          Tools – bbPress, and anything else that people use.

          Pathways – diving in and getting started. Finding an open support request, sorting the support requests to get unanswered ones. eventually becoming a mod, responsibilities etc.

          Tutorials & Guides: bbPress basics, How to Help, (other stuff from here: http://make.wordpress.org/support/handbook/)

          Reference – collection of stock responses. List of moderators

          Best Practice – support best practices. Dealing with problem users.

          Credits – all the awesome people who wrote the beautiful manual.

          That is totally off the top of my head. I’ve never actually provided support, am just in awe of others who do it. But I guess those would be the kinds of things.

    • karmatosed 1:24 pm on November 16, 2012 Permalink | Reply

      If it helps to fill spaces I can move into the theme review section – maybe that spreads the resources a little?

    • Andrea Rennick 1:53 pm on November 16, 2012 Permalink | Reply

      Put me down for Support & Docs.

    • Tom Auger 2:06 pm on November 16, 2012 Permalink | Reply

      As output from WPCS I have been working with Alex King on the Community Dev involvement piece. I think this could probably fit somewhere within the scope of Pathways, though perhaps our scope is a little larger. I would love to find a home for the work we are doing – this sounds like it.

    • Phil Erb 3:02 pm on November 16, 2012 Permalink | Reply

      I’ll also help out with Support.

    • Rachel Baker 3:21 pm on November 16, 2012 Permalink | Reply

      Shouldn’t Theme Dev & Theme Review be together?

      It seems to be that these handbooks would have much overlap, and keeping the content together would make it easier for them to be accurately maintained in the future.

      • christine 3:29 pm on November 16, 2012 Permalink | Reply

        I agree with Rachel. In fact developing themes without knowing about theme review and guidelines is not great.

      • kwight 3:58 pm on November 16, 2012 Permalink | Reply

        +1. It would be great to see theme review guidelines and best practices become the norm for theme development in general. The specifics of submitting to /extend/themes would become a footnote, instead of a frustrating new process for devs.

      • Siobhan 6:17 pm on November 16, 2012 Permalink | Reply

        I did think about putting them together, so here’s a bit of the reasoning behind why I think it’s a good idea to separate them.

        The aim of the handbooks is to get people to contribute to WordPress. They should make it as easy as possible. So rather than being comprehensive manuals that deal with every nuance of a contributor group, they should answer specific questions. For example:

        1. how do I contribute to WordPress core?
        3. how do I create a plugin for the repository?
        4. how do I help out on the support forums?

        When it comes to themes, I don’t think a single handbook that encompasses theme development and theme review is going to be as useful to users. Too much information is a barrier to learning. If someone wants to develop a theme, of course it’s useful for them to know how the theme review process works, but it’s not essential to them creating that theme. What they need to know is how to build a theme suitable for the repository. They shouldn’t have to filter through information about how the theme review team works.

        The theme review manual will be focused on the practicalities of reviewing themes for the WordPress repository. It should be focused on getting people to the point of “hmmm… I’d like to review themes” to actually reviewing themes. They should already know about theme development, and if they don’t we can direct them to the theme dev handbook. (this raises an interesting question about what level of knowledge we assume for each contributor group – i.e. for theme review do we assume that people can develop themes, for plugins do we assume that they are already experts in PHP? That’s something we’ll need to discuss around each manual).

        So:

        The theme development handbook will answer the question “how do I develop a theme for the WordPress theme repository?”

        The theme review handbook will answer the question “how do I review themes for the repository?”

        People don’t read documentation, so I think it’s important we give them what they need to achieve what they want to do, and nothing more. We can link to additional information, whether that’s in the codex or other manuals. After all, the handbooks will be one element of getting involved. Contributors are going to learn as more by getting involved with projects, hanging out in IRC chat rooms, and actually doing.

        Does that make sense? For the time being I’d like to conceive them separately. However, when it comes to creating the table of contents we may decide that there is a ridiculous amount of overlap and they should be merged. My concern with that is that by merging them we’re are conflating two different ways of getting involved with WordPress and they may lose their focus.

      • @mercime 8:50 pm on November 19, 2012 Permalink | Reply

        I agree with Rachel, Christine and Kwight. Theme development without knowledge of Theme Review rules/process == rejected theme.

    • Mel Choyce 4:28 pm on November 16, 2012 Permalink | Reply

      I started compiling/throwing together some UI guidelines a little while back: https://docs.google.com/document/d/1ZWPeUSFVYlMxClmHFjuAXuekXcZsLso49G3bDRquHcs/edit It’s kind of fallen to the wayside, but I’d be interested in continuing.

    • Justin Sainton 6:28 pm on November 16, 2012 Permalink | Reply

      Feel free to add me to plugins!

    • Abhishek Ghosh 8:42 pm on November 17, 2012 Permalink | Reply

      Umm, I am raising hand for Mobile and Theme Review. Theme Review needs 3-4 neutral peoples. Officially may be @raggedrobins you can keep yourself in the list.

      • Siobhan 6:42 pm on November 19, 2012 Permalink | Reply

        Thanks! Will add you to Mobile if that’s okay. I will probably add myself to Theme Review :)

    • Ipstenu (Mika Epstein) 4:45 pm on November 18, 2012 Permalink | Reply

      I’m in for Support (heh). And if you need a hand post-reviewing the Plugin one for ‘from the review team’s perspective’ I should be able to.

      Really we should all do ONE and no more than that, if possible. Otherwise we’ll all burn out :D

      • Siobhan 6:44 pm on November 19, 2012 Permalink | Reply

        Will add you to support :)

        I agree on the only one manual thing, particularly on the bigger ones – i.e. core, plugins, themes, mobile etc.

        Support and Docs should be pretty thin.

        I’ll also add you for reviewing the plugin one.

    • Carrie Dils 8:09 pm on November 19, 2012 Permalink | Reply

      Not sure where I fit in (Support or Docs?), but I’d like to jump in and help (Andrea made me do it). I’m probably most useful with reviewing, editing, or tutorials.

      • Siobhan 2:12 pm on November 20, 2012 Permalink | Reply

        We’d love to have your help! Either Support or Docs would be great. I’m also getting people to help with general editing and proofreading.

        • Carrie 8:38 pm on November 28, 2012 Permalink | Reply

          Toss me in whichever category (Docs or Support) needs folks the most. :)

    • Isaac Keyet 8:56 pm on November 21, 2012 Permalink | Reply

      @mrroundhill, @koke, and @daniloercoli will help write the Mobile handbook. I’ll help out as needed as well, but these guys are the lead devs for our main app projects. We discussed the handbook in this week’s mobile dev chat, summary coming to make/mobile shortly.

      • Joey Kudish 10:22 pm on November 21, 2012 Permalink | Reply

        I’ll help out with the mobile handbook as I can too, with my limited new contributor skills :)

      • Isaac Keyet 10:26 pm on November 21, 2012 Permalink | Reply

        • Siobhan 10:31 pm on November 21, 2012 Permalink | Reply

          Excellent – thanks guys! I’ll come along to the mobile chat next week and get some more information about specifics. tbh, the mobile contributor group is probably the most mysterious group to me so it’d be great to chat about it.

          @Joey – adding you to the list.

          Also, for the record – Rachel McCollin has offered (i.e. corralled) into helping with editing this one.

    • @mercime 4:32 am on November 28, 2012 Permalink | Reply

      I can help out in Theme Development and Theme Review

    • curtismchale 9:30 pm on December 11, 2012 Permalink | Reply

      I could jump in on Theme Review and Mobile.

    • Siobhan 2:39 pm on December 21, 2012 Permalink | Reply

      Everyone: please see updates to this on the docs blog:

      http://make.wordpress.org/docs/2012/12/21/plugin-and-theme-developer-handbooks-schedule/

      http://make.wordpress.org/docs/2012/12/21/best-practices-for-handbooks/

      http://make.wordpress.org/docs/2012/12/21/contributor-handbooks-schedule/

      FYI: if you’re volunteering for a contributor handbook, you should already be a contributor in this area. Otherwise it might get complicated writing the docs!

  • Siobhan 2:48 pm on November 1, 2012 Permalink | Reply
    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:

    • 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.

     

    • Brad Williams 2:55 pm on November 1, 2012 Permalink | 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 | Reply

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

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

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

          • Brad Williams 5:00 pm on November 1, 2012 Permalink | 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

              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 | Reply

          Same here. Would love to help with that.

      • Dougal Campbell 4:16 pm on November 1, 2012 Permalink | 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 | 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 | Reply

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

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

      I thought that the handbooks were being moved to learn.wordpress.org ( see Mika’s last post – http://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.

      • Andrea Rennick 3:00 pm on November 1, 2012 Permalink | Reply

        It;s just the USer Guide (sometimes we call it a handbook) that is going to Learn.

        • christine 3:02 pm on November 1, 2012 Permalink | Reply

          Hah, that makes sense. I just heard handbook and assumed it was all of them. But Duh, of course. Silly me.

          • Ipstenu (Mika Epstein) 3:19 pm on November 1, 2012 Permalink | Reply

            Also it’s a ‘We will move…’ There’s some hefty backend work that’ll need to be done before we can. But I do want to get all the handbooks out to learn eventually :D

      • Siobhan 3:30 pm on November 1, 2012 Permalink | Reply

        Yup – let’s have a chat about it some time over the next few weeks.

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

      Exciting stuff! Thanks for keeping it all moving!

    • Brandon Dove 4:51 pm on November 1, 2012 Permalink | 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?

      • Siobhan 4:58 pm on November 1, 2012 Permalink | Reply

        I suspect that the stuff at plan.wordcamp.org will probably stay where it is. It depends what Andrea thinks about it – either we’ll have to duplicate it or link to it.

        I think that the handbook will be worked on at: http://make.wordpress.org/events/handbook/ then we’ll make a lovely bundle at learn.wp.org. @ipstenu – can we get a handbook page made on the events blog?

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

        I think Aaron pinged Andrea about posting those guidelines to make.wordcamp.org/events

        • Siobhan 5:01 pm on November 1, 2012 Permalink | Reply

          Okay, perfect. Would be great to have them as part of the handbook.

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

      P.S. @vanillalounge has volunteered for the polyglots handbook :)

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

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

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

      Hi Siobhan,

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

      • Siobhan 9:05 pm on November 1, 2012 Permalink | 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 | Reply

          • Siobhan 5:13 pm on November 2, 2012 Permalink | 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

              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

              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

              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.

    • Kari Leigh Marucchi 9:26 pm on November 1, 2012 Permalink | 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 | 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.

    • Helen Hou-Sandi 4:56 pm on November 2, 2012 Permalink | 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 | 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 | 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.

    • Sara Rosso 5:34 pm on November 5, 2012 Permalink | 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.

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

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

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

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

    • jhoffm34 3:39 pm on November 9, 2012 Permalink | 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.

    • Japh 1:57 pm on December 6, 2012 Permalink | 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 :)

c
compose new post
j
next post/next comment
k
previous post/previous comment
r
reply
e
edit
o
show/hide comments
t
go to top
l
go to login
h
show/hide help
shift + esc
cancel