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

Introduction

Part One: Theme Basics

  • Including CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site. stylesheets and scripts (@iandstewart)
  • Template Tags (@clauzon)
  • 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. (@iandstewart)
  • Theme Files and Organization (@digisavvy)
  • Page Templates (@enricchi)
  • Template Hierarchy (@ozzyr)
  • Theme Functions (@iandstewart)

Part Two: Theme Functionality

  • 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) (@ozzyr)
  • Comments (@davidjlaietta)
  • Media
  • Navigation Menus (@jboydston)
  • Pagination (@thepixelista)
  • Post Thumbnails (@Brainfestation)
  • Sidebars (@thepixelista)
  • Translation (@Brainfestation)
  • widgets https://codex.wordpress.org/Widgetizing_Themes (@ancawonka)
  • Next and Previous Links https://codex.wordpress.org/Next_and_Previous_Links
  • Linking Theme Files and Directories https://codex.wordpress.org/Determining_Plugin_and_Content_Directories
  • Custom Headers https://codex.wordpress.org/Custom_Headers
  • Adding Admin Menus https://codex.wordpress.org/Adding_Administration_Menus

Part Three: Advanced Theme Topics

  • Child Themes
  • Theme Customizer [This still needs to be properly incorporated: https://codex.wordpress.org/Theme_Customization_API ]
  • Theme Security
  • 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. Best Practices
  • Theme Unit Tests https://codex.wordpress.org/Theme_Unit_Test
  • Validating Your Website https://codex.wordpress.org/Validating_a_Website)

Part Four: Theme Release

  • Required Template Files
  • Submission Process
  • Testing
  • Theme Review Guidelines
  • Writing Documentation (@sewmyheadon) ref: https://codex.wordpress.org/Theme_Review#Theme_Documentation

#contribute-day-2013, #handbooks

I got an email from Gary Jones about…

I got an email from Gary Jones about the CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site. property ordering in the CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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 contributorsCore Contributors Core contributors are those who have worked on a release of WordPress, by creating the functions or finding and patching bugs. These contributions are done through Trac. https://core.trac.wordpress.org. (or theme / 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 developers who also follow the WP standards) to go along through each property and decide which categoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. 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.

or

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 JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. 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?

#handbooks

Handbooks Design Comp – Preliminary

WP_Handbooks_comp-01a

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

Feedback?

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.

#devhub, #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: URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org
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 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 Handbook Office Hours are every Wednesday at 3pm UTC.

If you have any questions please let me know.

#handbooks

Plugin Developer Handbook Reporting Thread

This is the thread for weekly reporting on your activity on 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 Developer Handbook. Please posts here every Tuesday, reporting the following:

Last week: worked on [article title].
Link: URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org
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.

#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: URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org
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.

#handbooks

Theme and Plugin Development Handbook Office Hours

To help things move along with the 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 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.

#handbooks

Core Contributor Handbook Update 14th February

Chat Log

We had a chat about the CCH last night. Here’s what we discussed:

  • the tutorials on installing a desktop servers are nearly complete
  • we discussed whether we need to provide tutorials for both SVNSVN Apache Subversion (often abbreviated SVN, after its command name svn) is a software versioning and revision control system. Software developers use Subversion to maintain current and historical versions of files such as source code, web pages, and documentation. Its goal is to be a mostly compatible successor to the widely used Concurrent Versions System (CVS). WordPress core and the wordpress.org released code are all centrally managed through SVN. https://subversion.apache.org/. and GitGit Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. Most modern plugin and theme development is being done with this version control system. https://git-scm.com/.. We decided to de-prioritise Git for now and add it in the future if it’s needed
  • we discussed the issue of duplication across the handbooks. At the minute this isn’t an issue but it’s something that will need to be addressed at some point.

We can either:
a) copy the content from one place to another and make adjustments to make that content relevant to that specific handbook
b) have a centralised repository where the content is stored and then pulled into the handbook that it’s needed.

Both have pros and cons:

a) duplicating the content means that we can make it very specific to the handbook it’s in. This is better for users but more difficult in terms of management and keeping things updated – we’ll have a lot more to keep up to date.
b) centralising content – this would mean that we’ll lose the specificity which could be a problem in some situations.

I’m going to do some research into how other documentation projects deal with this sort of thing.

  • we had a discussion about article length. Some people like shorter articles, some people like longer.
  • we discussed having some style advice with regards to language in the handbooks
  • we need to have a free SVN GUI that we can recommend for Mac. @japheth recommended this: http://scplugin.tigris.org/ Other than that there is Versions but it’s a commercial product so I’m not sure if we can/should be recommending it.
  • we discussed translating the handbooks. How is this going to be done?

Actions

  • @rmccue to write up a general workflow for creating and submitting a patch
  • me to extend the style guide to include: “American English, “setup” vs “set up”/”login” vs “log in”, comma rules”
  • me to check with Simon Wheatley about the status of his multilingual 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

We’ll keep working through the tutorials and aim to do as much as possible by the next meeting at 22:00 UTC on Wednesday 27th February

#cch, #handbooks

Handbooks Wireframe v3

Handbooks-v3Based on feedback from the handbooks v2 wireframe posted earlier this week, as well as discussions in the CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. Contributor Handbook subcommittee on IRC (see log) here is a new one I worked up, which includes the following changes:

  • Shortened line length – I increased the text size so now there is approx. 75 characters per line. I think it strikes a nice balance between a comfortable line length and a decent amount of density, to keep pages from getting overly long.
  • Numbered headings and subheadings – There is some debate as to whether these should be manually or automatically generated. For now we’ll just try them on for size and see how they look.
  • “Scrolling” TOC – The table of contents is now moved to the sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme. area, where it is allowed to float free of the text, and follow the reader as they scroll.

And that’s about it. Everything else is held over from version two. Please click on the wireframe to view full size, and leave your thoughts in the comments section.

#handbooks

Handbooks Wireframe – v2

Handbook-wireframe-01Based on feedback from the handbooks wireframe posted last week, here is a new one I worked up, which includes the following changes:

  • More text and fewer images – This is probably closer to how a typical handbook page would look, which we would expect to have more written content and fewer illustrations than was shown in the first wireframe.
  • “Checklist” in the overview section – This would allow readers to determine at a glance what will be covered on the handbook page.
  • Added subheadings – To get a better sense of how subheadings would work in a handbook layout I added a few h3 headings. Lesser headings (h4-h6) are not represented but would follow suit. Note that subheadings are also displayed as a nested list in the TOC to show hierarchy.
  • Content box for displaying code – Styling would be similar to the other alert boxes, with a background color and icon.  Though not illustrated here, it would be ideal to use a syntax highlighter as well.
  • “Next Steps” section at the bottom – This is a good place to link to related pages within the handbook, as well as other external resources.

Please click on the image to view full size, and leave your thoughts in the comments section.

#handbooks