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:

We should use practical examples of code that will help people to learn
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:

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.
Schedule some google hangouts with contributor groups and volunteers to discuss best practices
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

Note to self: handbook translation. Bother @vanillalounge 😀
- mrmist 7:59 am on November 18, 2012
  
  I should really help out with Support and probably Docs.
toscho 1:07 pm on November 16, 2012

What would be the content of Support?
- Brian 1:09 pm on November 16, 2012
  
  Curious as well.
  - Siobhan 1:43 pm on November 16, 2012
    
    Support already has the beginnings of a handbook here: https://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 – bbPressbbPress Free, open source software built on top of WordPress for easily creating forums on sites. https://bbpress.org., 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: https://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

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

Put me down for Support & Docs.
- christine 3:28 pm on November 16, 2012
  
  Me too. I can help.
- Scott Basgaard 12:10 am on November 17, 2012
  
  Excited to be helping out in Support as well!
Tom Auger 2:06 pm on November 16, 2012

As output from WPCSWPCS The collection of PHP_CodeSniffer rules (sniffs) used to format and validate PHP code developed for WordPress according to the WordPress Coding Standards.
May also be an acronym referring to the Accessibility, PHP, JavaScript, CSS, HTML, etc. coding standards as published in the WordPress Coding Standards Handbook. 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

I’ll also help out with Support.
Rachel Baker 3:21 pm on November 16, 2012

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
  
  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
  
  +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
  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 coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.?
  3. how do I create a 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 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 filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. 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 PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.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
  
  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

I started compiling/throwing together some 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. 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.
- Siobhan 6:18 pm on November 16, 2012
  
  Thanks Mel! Will put you down for 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. stuff.
Justin Sainton 6:28 pm on November 16, 2012

Feel free to add me to plugins!
- Siobhan 6:40 pm on November 16, 2012
  
  Added
Abhishek Ghosh 8:42 pm on November 17, 2012

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

I’m in for Support (heh). And if you need a hand post-reviewing the 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 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 😀
- Siobhan 6:44 pm on November 19, 2012
  
  Will add you to support 🙂
  
  I agree on the only one manual thing, particularly on the bigger ones – i.e. coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., plugins, themes, mobile etc.
  
  Support and Docs should be pretty thin.
  
  I’ll also add you for reviewing the 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 one.
Carrie Dils 8:09 pm on November 19, 2012

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
  
  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
    
    Toss me in whichever categoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. (Docs or Support) needs folks the most. 🙂
Isaac Keyet 8:56 pm on November 21, 2012

@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
  
  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
  
  Mobile dev chat summary for nov 21, 2012
  - Siobhan 10:31 pm on November 21, 2012
    
    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

I can help out in Theme Development and Theme Review
curtismchale 9:30 pm on December 11, 2012

I could jump in on Theme Review and Mobile.
Siobhan 2:39 pm on December 21, 2012

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

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

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

https://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!