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

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