A Wireframe for Handbooks

During 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

Rachel McCollin 7:36 am on February 8, 2013

This looks really good, it’s great to see a consistent approach coming together as that will help users know what to expect so they can get on with learning without taking time to understand what’s going on on the page. It also helps handbook editors like me to see how we’ll be working.

I have a couple of comments/suggestions:

I would recommend a section at the bottom for further reading / links. Some Codex pages have links to some really useful tutorial and resources which can be very helpful.

I’m concerned about limiting sections to no more than a couple of paragraphs. Some of the content will be advanced and need quite detailed explanation. As long as this is done clearly and logically, I don’t see why it should be limited in length. The risk of limiting section length is that sections won’t go into the depth they need to so aren’t as useful as they could be.
- Jerry Bates (JerrySarcastic) 9:28 am on February 8, 2013
  
  The further reading section sounds like a good idea! 🙂
  
  The limit on paragraphs is probably a holdover from the User Manual, where being succinct makes more sense. I agree, for many handbooks the passages would be longer.
  - Siobhan 6:10 pm on February 8, 2013
    
    I agree with Rachel. Nothing should be limited in length. Just say what needs to be said in as few words as possible.
Siobhan 8:38 am on February 8, 2013
Thanks for this Jerry! There are a few things that will be really important:
- well differentiated headings from h2 – h6. So often I see headings that don’t look all that different to one another.
- alert boxes are so useful when writing docs. I like the little icons that you’ve put in them too.
- I’m not sold on image captions. I never use them for writing documentation. Readable screenshots with highlights & callouts, along with useful alt text, are better than a caption. Note that not all image will be full size.
Some things to think about:
- it’d be nice to have a box at the bottom that indicates which article the person should go to next. Here’s an example of what I mean: http://cl.ly/image/0b0R3s3Z0E22
- I -love- the checklist that they have at the start of the Rails guides: http://guides.rubyonrails.org/getting_started.html They are a really useful learning tool. The person can read what they’re going to become familiar with, then read the guide, then have a useful checklist that they can refer to. I wonder if it would be possible to incorporate that, either in 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. or at the top.
In an absolute dream world, the person would be able to check off what they’ve learned (or answer a few questions at the end) and track their progress through all of the handbooks, which would show on their .org profiles. That would be super-sexy. But, for now, a checklist would be fantastic 🙂
- Jerry Bates (JerrySarcastic) 1:05 am on February 13, 2013
  
  @raggedrobins – Something to think about re:captions… what about localization concerns? I agree that highlight and callouts are very effective, but it does mean more work for translators if those callouts are in English, for example.
  - Siobhan 2:46 pm on February 13, 2013
    
    Yes, you’re totally right. We’re going to have to avoid call-outs with text. Or use them only when they’re absolutely necessary.
    
    That still doesn’t sell me on captions though. Just an arrow or a highlight can say all that needs to be said. Maybe we don’t make captions a requirement and people just add them if they’re necessary?
Jerry Bates (JerrySarcastic) 9:44 am on February 8, 2013

I think there are a lot of things about the Rails guide that are worth borrowing from. I’ll add a checklist in my next iteration. Same for a box at the bottom for related links or next steps. 🙂

The 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 really drive me crazy when it comes to how headings are styled. I think h1 – h3 are all the same size, with h4 just slightly smaller; though not represented in this wireframe, I agree there should be clearer differentiation.
Anonymous User 1:01 pm on February 8, 2013

this might be crazy, but i’ve got a number of ebooks that i’ve released that had all of this done already, and color-coded based on topic… i’m discontinuing the sale of them and i could donate all the design work and original files if you’d like?

here’s a preview: http://tentblogger.com/ebook/

here is one of the example templates that i created as masters: http://i.john.do/Mld8
- Jerry Bates (JerrySarcastic) 6:30 pm on February 8, 2013
  
  Thanks John, those look really nice! I’d like to dig into them and see what can be adapted to work in a website (as opposed to an ebook) format but the design is really clean and straightforward.
  - Jerry Bates (JerrySarcastic) 6:39 pm on February 8, 2013
    
    I wonder what @raggedrobins thoughts are on pullquotes. I don’t know if they’re right for the Handbooks, but I have a soft spot for them.
    - Siobhan 6:43 pm on February 8, 2013
      
      I -love- pull quotes. But I don’t think they’re that suitable for this use-case.
      
      @John The ebooks look great! Will also have a look to see what we can adapt to the web.
- Jason Hoffmann 6:51 pm on February 8, 2013
  
  Yea I think that the “Action Plan” template on the last page would go great wit these handbooks (expanding on your point Siobhan). It shouldn’t be too much work to make those boxes checkable or even printable…
  - Jerry Bates (JerrySarcastic) 8:28 pm on February 8, 2013
    
    That seems to be in line with Siobhan’s comments as well; I also like the idea (and possibly tying in to .org user profiles) but it hints at some deep functionality that may be out of scope for the time being.
    
    Maybe we should start a “wish list” doc somewhere so we can keep ideas like this from getting lost. 🙂
Anonymous User 1:30 pm on February 9, 2013

Cool guys. Just let me know. I have all the original files. Glad to do it.
Anonymous User 2:00 pm on February 9, 2013

Also… look at this neat resource: http://uxmag.com/articles/improving-user-experience-in-manuals
Pingback: The WordPress Weekend Roundup - WP Daily
Pingback: Handbooks Wireframe – v2 « Make WordPress Documentation

Want to get involved?

Weekly meetings

A Wireframe for Handbooks

Notes about the wireframe

Want to get involved?

Weekly meetings

Notes about the wireframe

Share this: