Ready to get started?Download WordPress

Make WordPress Documentation

Tagged: handbooks Toggle Comment Threads | Keyboard Shortcuts

  • hanni 1:04 pm on February 27, 2014 Permalink | Log in to leave a Comment
    Tags: , handbooks   

    Handbooks Chat: 27th Feb 

    Present: @blobaugh, @caseydriscoll, @hanni, @NikV @philiparthurmoore,and @sams.

    1.Plugin Developer Handbook

    The revised outline proposal was finalised last week by @blobaugh and @hanni, who are this week working on getting the content copied over from the “old” to new structure. If you take a look at the handbook you’ll see this is well underway, and we’re hoping to complete the merge in-time for the sprint.

    A backup was taken of all content prior to starting this, so as to be able to “revert” in case of disaster, and also to allow the restoration the proper metadata for each and every contributors to each section when appropriate.

    The structure can be seen here: https://docs.google.com/spreadsheet/ccc?key=0Ak0ISjkNpXRIdHRVSDlFOWlBakYwRnNJZV9rbDIyOHc&usp=sharing#gid=0

    The first section is very much in draft form, and is intended to be written by a couple of folks going through the process of writing their own plugin (including @hanni), so no-one should be alarmed by the apparently bizarre state at present.

    Note: until we’ve ported the numbers etc. we’ll not replace the link in either the spiffy new nav or the sidebar, so as not to confuse. This also motivates us to get it finished in time for this weekend’s Docs Sprint. Whilst the sprint is based in Seattle, everyone is welcome to participate, wherever they are.

    Admin-wise, @blobaugh is leaving for a trip to Uganda on the 5th March, and will return on the 21st. As such, Ben is eager to get things in tip-top shape prior to his departure.

    During @blobaugh‘s trip, @hanni will be the point of contact for the Plugin Developer Handbook.

    2. Theme Developer Handbook

    Due to travel, Theme Developer Handbook Editor @sewmyheadon was unable to make this week’s meeting, so @hanni attempted to fill his shoes for the day.

    @philiparthurmoore kindly joined to help kick-off the effort to integrate some of the fantastic themeshaper.net content. As per previous recent handbook discussions, focus for the Theme Developer Handbook is very much on stage (i).

    To this end, over the next couple of weeks @philiparthurmore will be working on an initial one page summary distilling the themeshaper content down to the basics of getting from zero to your first theme, upon which we can then expand as necessary.

    He’ll have an outline ready for the Docs Sprint on March 1st, such that any folks present can see where things are going and lend a hand if they so desire.

    If anyone else is interested in helping with this, please do leave a comment here or ping Philip, Eric, or myself.

    Thanks again everyone!

  • hanni 6:41 pm on February 18, 2014 Permalink | Log in to leave a Comment
    Tags: handbooks, stateofthehandbooks   

    Where are we with the Plugin and Theme Developer Handbooks? 

    Hanni! You just posted something about a handbook status meeting but what’s actually happening with these mythical creatures?

    Plugin Developer Handbook Stasis

    We’ve now a proper (as opposed to acting) editor for the Plugin Developer Handbook, in the very capable form of Ben Lobaugh (@blobaugh).

    . Ben and I are in the process of re-jigging the structure and existing to fit with the two-tiered goals of the handbooks. Watch this space! The new outline will be ready for the Docs Chat this week, Feb 20th.

    Goal Parity

    With little policing of contributions over these past months, we’re in danger of creating two unwieldy information dumps as opposed to digestible handbooks.

    A rough goal could be stated as providing an overview for each handbook such that:

    i) The reader gets into the book and to show them how to build a simple theme, or plugin, so they can see how easy it is and get introduced to the necessary and basic building blocks.

    ii) Then, once that overview is complete for each handbook we’ll proceed with more in-depth dives into each section as and when is necessary.

    With the current state of the handbooks, we’ll be focusing on finessing (and constructing!) i) for the foreseeable future.

    New Contributors

    i. Plugin Developer Handbook
    We have some great news about increased interest in contributing to the project! (Thanks to all those who graciously caved in to my pestering are champing at the bit to give back and get involved.)

    I’m so excited to announce that Woo are eager to give of their time to help the Plugin Developer Handbook effort, in particular: @scottbasgaard, @hlashbrooke, @mikejolley, and @corsonr. Thanks, Woo!

    The guys at fooplugins, @bradvin and @awarner20, are also on board.

    Thrilled to add that @trepmal, @shaunandrews, @johnny5 (tech reviewing), @westonruter, and @pcrumm have also kindly offered to give of their time, as and when they can.

    Existing contributor @jackreichert is also eager to help with the renewed push.

    With such a great bunch we should be able to get things moving at a good pace. I’ll be in touch will all of the above over the next few of days to make sure everyone has the correct access and is able to hit the ground running.

    ii .Theme Developer Handbook

    @philiparthurmoore is eager to work on the Theme Developer Handbook, as is @nudge – good news for the project! Thanks, you two.

    Looking to get involved?

    If you’re looking to help out with one of the handbooks, feel free to come to any of the weekly check-in meetings, ping myself or the editor for the handbook in question, leave a comment on this post, or join the regular weekly Docs Team chat.

    Again, as noted in @kpdesign’s notes from last week’s chat, I take full responsibility for the stalling of the Handbooks. Onwards and upwards, folks!

    Lastly, thank you to everyone who has given, and continues to give so much of their valuable time to what is truly a community effort.

  • hanni 5:14 pm on February 18, 2014 Permalink | Log in to leave a Comment
    Tags: handbooks, progress   

    Weekly Handbooks Check-in 

    It’s time to get back on the handbook bandwagon, folks!

    We’re starting a weekly check-in meeting between those responsible for the progress of a number of the handbooks, @hanni (general helper), @sewmyheadon (editor of the Theme Developer Handbook), and @blobaugh (editor of the Plugin Developer Handbook), and anyone else who is both interested in the progress of the above, and wishes to find out more about getting involved.

    The goal of this status meeting is to ensure that we’re keeping an eye on content coming in, making the requisite progress (here’s to getting back the momentum we lost!), doing all we can to support both current, and potential contributors. Most importantly, we want to keep the outlines of the handbooks on track to meet the common goals of outlining the process to build both a theme and plugin for those newer to the process, whilst also providing an appropriate level of reference for those familiar more familiar with theme and plugin development. More to come on this subject.

    Please feel free to join, it’ll be in #wordpress-sfd at 5PM Pacific, every Wednesday. Open to all!

  • Ryan Markel 6:56 pm on July 28, 2013 Permalink | Log in to leave a Comment
    Tags: , handbooks, theme developer handbook   

    Theme Developer Handbook @ Contribute Day 

    oK; let’s take some bits of the handbook – each bit should be reviewed for usefulness and accuracy. Keep in mind that we’re aiming for a resource that people can use to check as they develop a theme.

    Here’s the list of topics – each should get a pass from a volunteer and then pass it to Se for a style review. Tick off the topic when you take it and add any notes by editing the post. When Se says “it’s done,” she’ll add another note and we’ll then consider it to be checked in. :)


    Part One: Theme Basics

    Part Two: Theme Functionality

    Part Three: Advanced Theme Topics

    Part Four: Theme Release

  • Siobhan 3:29 pm on April 30, 2013 Permalink | Log in to leave a Comment
    Tags: handbooks   

    I got an email from Gary Jones about the CSS property ordering in the Core Contributor Handbooks. He says:

    Currently the CCH says the CSS properties should be grouped as:

    • Display
    • Positioning
    • Box model
    • Colors and Typography
    • Other

    I don’t think this is prescriptive enough, and it’s certainly not easy for core contributors (or theme / plugin developers who also follow the WP standards) to go along through each property and decide which category it fits in to before having to manually move lines up and down.

    As part of the Genesis 2.0 CSS reorganisation, I came across http://csscomb.com – it’s available as a plugin for most of the popular editors, but also as an online tool as well. It already comes with tests, but I also did some with multiple properties in a rule (i.e. padding using rem, then px fallback) and mis-ordered browser-prefixed properties, and it sorted them perfectly. It also keeps any whitespace between the : and value, to keep browser-prefixed values lines up, as per the CCH.

    If you head to the online tool, then click on Settings, you’ll see it pops-out with a comprehensive list of CSS properties, including ones for CSS3 and prefixed properties, which WP might not have made a decision about if they don’t use them.

    I think this tool can be used in one of two ways:

    1) Amend the CCH so that Display comes after Positioning, so it then matches the CSScomb defaults and can be easily used by anyone online or in their editor without further set up, making it easy to automate the property ordering process.


    2) Take the list of properties, and update it to reflect the order that WP prefers, and make this available as a list (Gist) that can be copied back into the online settings, and as an equivalent file for use in editors (Sublime Text 2 uses a JSON file), including a list of instructions for both.

    Being more descriptive, by having someone else keep track of the full list of properties (including CSS4, CSS5 properties etc.), and having a tool that is available for those with and without compatible editors, means that the process can be automated, and a chunk of potential human error is removed.

    I’d love to hear what the docs / CS folks have to say about it using this tool. Being able to open a .css file, select all, then hitting a keyboard shortcut to have it automagically match the WP standards has got to be worth investigating?

    What do you guys think? Is this something we want to look into?

    • Jason Hoffmann 3:34 pm on April 30, 2013 Permalink | Log in to Reply

      I think that directing people to this tool is a great idea for beginners who are just getting into CSS and want to make sure that their code is neatly organized. I also think it would be bit silly to amend the rules, attach that to a gist, and a bunch of steps for people to even use the tool. It would be much much easier, and to my mind preferable, to amend the CCH to place display after positioning.

      The order of CSS Properties is mostly a matter of taste, and does not effect specificity or the cascade so there are no functional drawbacks.

      For those that are seasoned front-end devs, they will have their own way of organizing properties and a tool like CSS comb may not be necessary to them. If it is, they will have the knowhow to tailor it to their needs. Beginners, on the other hand, should have access to a tool that is simple to use without extra steps.

      • Gary Jones 3:55 pm on April 30, 2013 Permalink | Log in to Reply

        For simplicity, suggestion 1 would be my favourite as well, for the reasons you’ve suggested (too many extra steps), but I wanted both options to be considered (the implicit third option is that the tool isn’t recommended, and beginners are left to fend for themselves). It then comes down to whose (collective?) taste decided on the order currently in the CCH in the first place, and whether they’re happy to have it amended to make using this tool so much easier.

        Thanks for your feedback Jason :-)

        • Kim Parsell 4:10 pm on April 30, 2013 Permalink | Log in to Reply

          Gary, to my knowledge, Helen Hou-Sandi worked on the final CSS standards, and moved them from the Codex to the handbook. She should be able to shed some light on why the properties are ordered that way in the coding standards.

          I have to agree with Jason’s suggestion as well (amend the CCH). You might talk to Helen about your other ideas, see what she thinks. There is a Related Links section (http://make.wordpress.org/core/handbook/coding-standards/css/#related-links) where this information could be included.

    • Eric Amundson 4:06 pm on April 30, 2013 Permalink | Log in to Reply

      +1 for amending the CCH to place display after positioning; much easier all around.

  • jerrysarcastic 3:37 pm on March 25, 2013 Permalink | Log in to leave a Comment
    Tags: design, handbooks   

    Handbooks Design Comp – Preliminary 


    Click to enlarge

    Last week I presented an initial design comp for the handbooks in IRC [log] and we discussed it there, and I’m posting here to continue the conversation.  This design builds on previous wireframes, but is very much a preliminary design, as we’re still not clear what theme (or themes) we’ll be using to house the various handbooks yet.

    What we do know is that at least some of the handbooks will find their home in existing P2 blogs, so that is what I’ve started with here.

    How do you design without a theme?

    Legibility, scannability, whitespace, and typography are all things that should serve the content, not the theme, so that is where I’ve focused for now.

    I’ve also tried to design with overall flexibility in mind as well; a font change and a few tweaks are all that should be needed for this design to work with most themes.

    Here are some highlights:

    • Body copy – The body is set in 16px with a 24 px line height for whitespace, about 80 characters per line.  Helvetica Neue is used here to match P2 blogs but can be easily substituted.
    • Headings – Beyond varying font sizes, I also outdented h1 headings to make them stand out from the body copy.  For h2-h6 headings, I indented them from the body copy, and added border-left to create an added graphic element.  [See all headings]
    • Text Containers –  Content boxes for code, info, alerts, and next steps are color coded to stand out from the body copy.  I’ve used Genericons for the related icons as well.
    • TOC – This is generated automatically, based on the headings on the page.  Only h1-h3 headings are represented for now, and the font weight of each has been varied to make this easier to scan as well.   I’m not sure if lesser (h4-h6 headings) even have a place in the TOC.


    Since we still need to figure out the theme issue, this is a good stopping point for the design.  Please leave your feedback in the comments so they can be included in the next round! :)

    EDIT:  For some context, here is what the design looks like mocked up inside a P2 theme.

  • Siobhan 8:23 pm on March 8, 2013 Permalink | Log in to leave a Comment
    Tags: handbooks   

    Plugin & Theme Developer Handbook Workflow Changes 

    Things aren’t moving along as quickly as I had hoped, but now that I’m working on WordPress full-time I’m hoping that i can help to move things along. I’ve had a chat with Rachel and Tom and we’ve decided to change tactics.

    First of all, the schedule is out the window. I created that to write in a linear fashion but as a writer myself I should have taken into account the fact that manuals are rarely written linearly. Instead of having deadlines, we’re going to instead do the following:

    • if you wish to be involved in either handbook, please set aside 2 hours per week for writing. If you are unable to dedicate this time please make Tom or Rachel aware of it.
    • please only assign yourself to a maximum of two items in the spreadsheet
    • every Tuesday, I’d like for each person to post on either:

    the theme developer handbook reporting thread
    the plugin developer handbook reporting thread.

    Please follow this format:

    Last week: worked on [article title].
    Link: URL
    Issues: (list any issues you’re having or assistance you need)

    Next week: working on [article title]

    • if you miss two Tuesdays in a row then we’ll get in touch to see if everything is okay. If you can’t keep it up we will remove you from the spreadsheet (you’ll still get credit for everything you’ve done, but we need to keep things moving along.

    Theme and Plugin Developer Handbook Office Hours are every Wednesday at 3pm UTC.

    If you have any questions please let me know.

  • Siobhan 8:22 pm on March 8, 2013 Permalink | Log in to leave a Comment
    Tags: handbooks   

    Plugin Developer Handbook Reporting Thread 

    This is the thread for weekly reporting on your activity on the Plugin Developer Handbook. Please posts here every Tuesday, reporting the following:

    Last week: worked on [article title].
    Link: URL
    Issues: (list any issues you’re having or assistance you need)

    Next week: working on [article title]

    Note that the Plugin Developer Handbook Office Hours are at 3pm UTC every Wednesday.

  • Siobhan 8:21 pm on March 8, 2013 Permalink | Log in to leave a Comment
    Tags: handbooks   

    Theme Developer Handbook Reporting Thread 

    This is the thread for weekly reporting on your activity on the Theme Developer Handbook. Please posts here every Tuesday, reporting the following:

    Last week: worked on [article title].
    Link: URL
    Issues: (list any issues you’re having or assistance you need)

    Next week: working on [article title]

    Note that the Theme Developer Handbook Office Hours are at 3pm UTC every Wednesday.

  • Siobhan 3:15 pm on February 26, 2013 Permalink | Log in to leave a Comment
    Tags: handbooks   

    Theme and Plugin Development Handbook Office Hours 

    To help things move along with the theme and plugin dev handbooks, we’ve decided to arrange for weekly office hours during which myself, Tom and/or Rachel will be available.

    The office hours will be time for us to review where we are and deal with any queries or issues. You’re also welcome to come along during that time and collaboratively work on any content.

    The office hours will be every Wednesday starting on 6th March:

    We’ll be meeting in irc.freenode.net in the #wordpress-sfd chat room.

    Note that on the 13th March, both Rachel and I will be out in the evening, so the Theme Dev folks can come along to the plugin dev chat if they have any issues. Otherwise, we’ll meet as usual at 8pm on 20th March.

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