Tag Archives: handbooks

jerrysarcastic 2:03 am on February 8, 2013
Tags: handbooks   

A Wireframe for Handbooks

Handbook-wireframe-01During the IRC meetupMeetup All local/regional gatherings that are officially a part of the WordPress world but are not WordCamps are organized through https://www.meetup.com/. A meetup is typically a chance for local WordPress users to get together and share new ideas and seek help from one another. Searching for ‘WordPress’ on meetup.com will help you find options in your area. today (read the log) @siobhan shared the Handbooks Style and Formatting Guide that she has been working on; it’s purpose is to unify the tone and style of all the (awesome!) WordPress handbooks projects that have started popping up recently.

Also discussed in the meetup was the need for a better design for the handbooks, starting with wireframing. As I already toyed with a quick wireframe for the User Manual project, which has similar goals as the handbooks, to help jumpstart the discussion I thought I would post it up here.

Notes about the wireframe

It’s a bit early yet to know what the final home of the various handbooks will be. Some may live on dotorg P2P2 P2 or O2 is the term people use to refer to the Make WordPress blog. It can be found at https://make.wordpress.org/. sites, and others may use different themes instead.  For that reason, no sidebars, site navigation, and other theme-related features are shown in this wireframe; this is focused on the content column only for now.

  • Breadcrumbs – Nothing fancy, just lets the reader know where they are, based on the parent/child relationship of the page.
  • TOC box – Displayed at top of article is a table of contents. A lot of dotorg P2 blogs already feature this in an unstyled form, and it is generated automatically from the headings on the page.
  • Headings – Ideally, as mentioned in the style guide, only one topic or step will be used per heading. Generous top/bottom margins add whitespace between these “sections” of content, to keep the information easily scannable and digestible.
  • Body Copy – As with the headings, good whitespace between paragraph elements.  There should not be more than a paragraph or two per heading.
  • Images/Videos – These are always displayed at full width, which is helpful for detailed screenshots.  Can be linked to a larger image,  displayed in a lightbox or other modal window (not shown) so the reader does not have to navigate away from the current page when getting a closer look.
  • Image Captions – Descriptive captions help explain the image, and are also named (Fig. 1, Fig. 2, etc.) with matching footnotes in the text, to help readers link the instruction text to the related illustration.
  • Alert Boxes – These will likely use the blockquote HTMLHTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites. tag with an added class for styling and possibly adding an icon. Boxes for “tips” and “warnings” are represented, but others can use a similar format.

That’s pretty much it.  Leave you thoughts/feedback in the comments below, so we can start building a home for all these great new handbooks.

#handbooks

Siobhan 11:29 pm on January 30, 2013
Tags: , handbooks   

Core Contributor Handbook Chat 30th January Summary

Read the Chat Log

We had a great discussion about the CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. Contributor Handbook this evening. Here’s what we covered:

1. Status update

We went over what we’ve done, and reviewed the Table of Contents.

2. Actions Decided

@raggedrobins to put together a style guide & writing guidance
Create ToC for the handbooks
Look for source material that we can incorporate into the handbook
Start writing additional articles for the handbook

3. Other CCH items discussed

We discussed using some of the functionality that is used in the bbPressbbPress Free, open source software built on top of WordPress for easily creating forums on sites. https://bbpress.org. and BuddyPress codices for author attribution and last updated, date created. See here.

Totally off topic but we discussed creating a better code reference for WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ than we currently have in the Codex. We can return to this discussion at a later date.

The next CCH chat will be on Wednesday 13th February at 2200 UTC.

#cch, #handbooks

Siobhan 2:25 pm on January 29, 2013
Tags: , handbooks   

Core Contributor Handbook Chat 30th January

We’ve got a group of people who are keen to work on the CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. Contributor Handbook so I’m going to start moving things forward. We’ve done an audit of the content and have put together a new Table of Contents.

To kick things off we’re going to have a chat. This will be:

2200 UTC
Wednesday 30th January
Location: #wordpress-sfd
i.e. following the core dev chat

If you’re already involved with the CCH or would like to get involved, or have an opinion on it, please come along.

#cch, #handbooks

Rachel Baker 9:51 am on January 24, 2013
Tags: handbooks   

Theme Handbook Update Jan 24th

Friends, Romans, Theme developers, lend me your hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same.…and let us together take “action”.
For those that haven’t heard, I am the editor of the Theme Handbook. I am responsible for  bringing together the different theme topics, to be written by volunteers like you, into a cohesive reference on building a WordPress theme.
With the help of Siobhan, Chip, and many others we have compiled the table of contents for the Theme Handbook.  The Handbook contains five different sections that are split among many different topics:
  • Introduction – Content Management in WordPress, What is a Theme?
  • Theme Basics – Template Files, The LoopLoop The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. https://codex.wordpress.org/The_Loop., Template Tags, Theme Functions, Including CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site., Including JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/.
  • Theme Functionality – Comments, Sidebars, Navigation Menus, Thumbnails, Image Galleries, 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), Translation, Misc.
  • Advanced Theme Topics – Best Practices, 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./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., Theme CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings., Theme Options, Security, Child Themes
  • Theme Release – Required Files, Testing, Writing Documentation, Submission Process

Our team is in need of a few more contributors.  Each topic will be written by one or more volunteer contributors.   If you know of anyone that would be interested or perhaps a good fit for an open section please do let me know.

The next steps are to get the current volunteers access to the Theme Handbook site, find volunteers for the unclaimed sections, and get this show on the road.
The next IRC Docs Chat is today at 2100 UTC on #wordpress-sfd.  Hope to see you there.

#handbooks

Siobhan 1:03 pm on January 21, 2013
Tags: handbooks   

Plugin and Theme Developer Handbook Editors

I’m really happy that we have identified two editors for 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 and Theme Developer Handbooks:

  • Plugin Developer – Tom McFarlin
  • Theme Developer – Rachel Baker

Rachel and Tom will be leading and managing each of the handbooks, with me on hand to support them with anything that they need. We’ve almost finalised the table of contents for each of these handbooks, so writing will be able to begin soon.

I’ve added Rachel and Tom as editors here so they’ll be posting about their respective handbooks. As a reminder, here is a list of the people who are involved with these two handbooks:

Plugin Dev

Pippin Williamson
Dougal Campbell (Best Practices)
Thomas Griffin
Maor Chasen
Justin Sainton
Daniel Bachhuber
Drew Jaynes

Theme Dev

Chris Reynolds
Tammie Lister
Jay Hoffman
Mario Peshev
Suzette Franck
Drew Jaynes

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
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./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. – Mel Choyce/Shane Pearlman

We’re low on numbers for Theme Dev so if you know of anyone who would like to get involved send them our way.

#handbooks

Siobhan 12:31 pm on January 9, 2013
Tags: handbooks   

Handbooks Step 1: Creating the Table of Contents

We’re at the first stage of the handbooks, creating the table of contents. Here’s what you do:

Theme and 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 Developer Handbooks

I have created two spreadsheets for these handbooks. Please go into the spreadsheets and start adding sections to the ToC. I’ve added links to ToC that were suggest to me for inspiration.

By creating the ToC like this we’ll be able to get an overview of the whole thing before we start creating pages. You can find them at:

The ToC should be finished by 21st January. We’ll review where we are at next week’s chat.

@rachelbaker will be the editor for the Theme Developer Handbook so she’ll be taking the lead on that one.

Am still looking for an editor for the Plugin Dev Handbook let me know.

When the ToC is finished I’ll create the pages and we’ll move on to the next step.

Contributor Handbooks

Most of these will be created at make.wordpress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org//area/handbook

You can see examples at:

Polyglots will be created on make/docs. We’re using Edit Flow to manage the editorial workflow here. If anyone else wants to build theirs on make/docs just let me know.

Core is a little bit different. It’s already got a lot of content there. I’m going to do an audit of the current content and then work with @japh and @danielbachhuber to see what we need to add and what needs to be fleshed out.

If you have any questions or if there’s anything that I’ve missed let me know.

#handbooks

Siobhan 11:28 pm on January 2, 2013
Tags: handbooks   

Handbooks Kick-off Chat

Next week’s Support/Docs Chat will take place in #wordpress-sfd on Tuesday 8th at:

  • 2100 UTC
  • 9pm London
  • 4pm US Eastern
  • 1pm US Pacific
  • 2:30am (Friday) Bangalore

Let’s make this the kick-off chat for the handbooks. If you want to throw around ideas before then feel free to grab hold of me in #wordpress-sfd from Monday next week.

#handbooks

Siobhan 2:35 pm on December 21, 2012
Tags: handbooks   

Plugin and Theme Developer Handbooks: Schedule

In January, it’ll be time to get started working properly on the handbooks. Start date will be January 7th (since I’m going to be on holiday until then 🙂

I’ve made a few different schedules since some handbooks will take ages. Others will take only a month or so of work.

Note: we will be looking at other user-focused handbooks to create some time in the new year. If you don’t feel up to 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 or theme dev, or don’t fit into the other contributor handbooks, we will find a home for you!

  • Each manual will need an editor. The editor will own the manual and be responsible for running their group, herding content, and editing (I’ll help out however I can). They will also be responsible for regularly reporting on how things are going. If anyone would like to volunteer to be an editor please let me know in the comments. Please let me know what experience you have in a) the area b) with editing and organising.
  • As you are adding content, please add terms to the glossary as you go along.
  • The first two weeks will be creating the ToC. Once that’s done I will have the style guide ready for when you start writing.
  • I’ll post a spreadsheet for creating the table of contents on 7th January, along with information about workflow.

Plugin and Theme Developer handbooks will be built at:

  • make.wordpress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org//docs/theme-dev/
  • make.wordpress.org/docs/plugin-dev/

Theme & Plugin Developer Handbooks Schedule

Jan 7th – 21st Draw up table of contents.
Kick-off meetings.
Jan 21st, 2013 Writing: The Basics
February 22nd, 2013 Complete Part 1: The Basics
Start work on Part 2: Requirements
March 15th, 2013 Complete Part 2: Requirements
Start work on Part 3: Functionality
May 3rd, 2013 Complete Part 3: Functionality
Start work on Part 4: Settings and Options
May 31st, 2013 Complete Part 4: Settings & Options
Start work on Part 5: Security
June 28th, 2013 Complete Part 5: Security
Start work on Part 6: Best Practices (hoping best practices will already be completed by various groups and will only require editing
July 19th, 2013 Complete Part 6: Best Practices
Start work on Part 7: Releasing on WP.org
August 30th 2013 Complete Part 7: Releasing on WP.org
Finish off glossary. General editing and tying up of lose ends.
September 27th, 2013 Complete!

Thanks to @nacin for the table!

If you want to organise a documentation sprint around a handbook, either virtually or in person at a WordCampWordCamp WordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more., that would be great! Just let me know and I’ll help to make it happen.

#handbooks

Siobhan 2:09 pm on December 21, 2012
Tags: handbooks   

Best Practices for Handbooks

The following handbooks will need best practices drawn up:

  • Theme Developer – 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./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., 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), General Best Practices
  • 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 Developer – UI/UX, Accessibility, General Best Practices
  • CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. – UI/UX, Accessibility, General Best Practices
  • Mobile – UI/UX, Accessibility, General Best Practices
  • Docs – Accessibility

(maybe we want a best practices doc for forum mods @ipstenu?)

Ideally, someone would take responsibility for UI/UX and would get together a group of people to draw up best practices that can be included within the handbooks. Based on people who have expressed interest in the past, here’s what I’m thinking:

  • Plugin Development Best Practices – @dougal
  • Theme development best practices – no volunteers yet
  • Theme/Plugin UX & UI- @justlikeair and/or @melchoyce
  • Accessibility for all of the handbooks – @esmi & the accessibility group
  • Core UI/UX – no one yet but maybe @helen can suggest someone?
  • Core – no one yet but maybe @nacin can suggest someone?

If I’ve mentioned you there and you’re still interested, please let me know in the comments. If you’re not mentioned but you are interested also let me know.

If you take responsibility for this, you’ll be expected to work with a group of appropriate people that you select to come up with best practices. Having a few Google Hangouts and drawing up a Google doc might be a good way to go about it. You’ll be expected to complete the best practices docs by:

  • Core, Mobile, Docs – April 26th
  • Theme Dev & Plugin Dev – July 19th

Okay, let me know!

#handbooks

Siobhan 1:49 pm on December 21, 2012
Tags: handbooks   

Contributor Handbooks: Schedule

In January, it’ll be time to get started working properly on the handbooks. Start date will be January 7th (since I’m going to be on holiday until then 🙂

Note: we will be looking at other user-focused handbooks to create some time in the new year. If you don’t feel up to 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 or theme dev, or don’t fit into the other contributor handbooks, we will find a home for you!

In general, there are people from each of the contributor groups putting together the handbooks. They will help to wrangle content etc. Here’s where we stand at the minute:

Mobile
The mobile team will be writing the content, and Rachel McCollin is going to help out with editing. They have no content yet 🙁

Support
@ipstenu will ensure that the content is created for the forum moderator handbook.

CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.
Myself, @japh and @danielbachuber and any other volunteers will be working on core. There is a lot of content there already which we can move around, structure, edit, and add more content as needed.

Docs
Myself and @DrewApicture will put together the docs handbook. If anyone would like to help please let me know and I’ll add you as an editor.

Polyglots

@vanillalounge has take responsibility for this. He will see if anyone else from polyglots want to be involved.

Theme Review & Events
I’ve not heard too much from them but will update when I do. It looks like events is building their own training materials in any case.

The below schedule is really for Mobile, Core, and Polyglots. Forum Moderator and Docs won’t take all that long so can get started with everyone else and get through it as quickly as they like.

Contributor Handbook Schedule

Jan 7th – 21st Draw up table of contents.
General kick-off discussion, questions etc.
Jan 21st, 2012 Writing: Requirements
February 1st, 2013 Complete: Requirements
Start work on Tools
February 15th, 2013 Complete Tools
Start work on Pathways
February 28th, 2013 Complete Pathways
Start work on Tutorials and Guides
April 12th, 2013 Complete Tutorials and Guides
Start work on References
April 26th Complete Refrences
Start work on Best Practices (am hoping these will be mostly completed already
May 17th, 2103 Complete best practices. Revise, edit, proofread.
May 31st Complete!

Thanks to @nacin for the table!

If you want to organise a documentation sprint around a handbook, either virtually or in person at a WordCampWordCamp WordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more., that would be great! Just let me know and I’ll help to make it happen.

#handbooks