Handbooks Wireframe v3

Welcome to the official home of the WordPress Documentation Team.

This team is responsible for coordinating all documentation initiatives around WordPress, including the handbooks and other general wordsmithing across the WordPress project.

Want to get involved?

Start here to find out more about what we do and how to contribute:

Onboarding to Documentation Team: An overview of what we do and how to collaborate
Documentation Issue Tracker on GitHub: Submit any Documentation Team-related issues on GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/

Weekly meetings

Join our discussions of documentation issues here on the blog and on Slack.

The documentation team holds weekly office hours and monthly Contributor Days on each Tuesday of the month in the #docs SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. channel. It’s also where you can contact the team at any time outside meetings.

Based 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

Jerry Bates (JerrySarcastic) 8:21 am on February 14, 2013

Also, thinking about how things might look on a tablet sized screen (in case we choose to use a responsive theme) I though it might be good to collapse the TOC so it still follows the reader when they scroll, without obstructing the content. Should they need to jump to a different section, a tap will reveal the TOC, like so:
- BFTrick 1:58 pm on February 14, 2013
  
  I think that’s a great idea!
  
  My only concern is that in iOSiOS The operating system used on iPhones and iPads. apps (I’m thinking gmail, facebook, & twitter) the menus are always on the left. Do you think it would be a big deal if we moved it to the left for the tablet size?
  - Jerry Bates (JerrySarcastic) 6:07 pm on February 14, 2013
    
    If we go this route, I don’t see why not. 🙂
- karmatosed 6:25 pm on February 14, 2013
  
  Maybe something like (just an idea and the icons certainly would have to change and it needs text and 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) checks):
  
  I also don’t think this ‘has’ to be just on non desktop devices. It could work for the larger screens also as focuses on the content.
  - Jerry Bates (JerrySarcastic) 6:43 pm on February 14, 2013
    
    I like it!
esmi 10:42 am on February 14, 2013

Do we have to have the floaty TOC thing? Personally, I loathe these with an absolute vengeance. On a more serious note, I’m also concerned as how it would impact overall 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). any chance of a compromise – an option that would allow the reader to un-dock the TOC if they want?
- Siobhan 5:39 pm on February 14, 2013
  
  I would like to see a little X that the user can click so that if the user wants they can stop it scrolling and it sits 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.. An X or a link that says something link “Stop scrolling” or “Stick to sidebar” or something like that.
  
  There should be a way to stop it scrolling as some people (like me) will find it annoying.
- karmatosed 6:08 pm on February 14, 2013
  
  Sorry to say but I’d really advise against the floaty thing it’s not a great experience – there’s a reason it’s not a common used feature on tablets/mobile. Also people often use the left to scroll down which means they will hit it constantly.
  
  More common (and more user friendly) are slide in / out menus or we can easily have a bottom wrapper or just a click to top minimal menu.
  
  Aside from that it’s cool I like the idea of having a set series of styles.
  - Mel Choyce 6:43 pm on February 14, 2013
    
    Actually, sticky menus have been shown to be good usability: http://uxdesign.smashingmagazine.com/2012/09/11/sticky-menus-are-quicker-to-navigate/
    - Jerry Bates (JerrySarcastic) 6:47 pm on February 14, 2013
      
      I agree, but have to question if a sticky TOC is as *useful* as sticky site navigation.
      
      I’m divided; I personally don’t use TOCs for in-page navigation, though it sounds like others do like and use that feature, based on feedback from the other wireframes.
      
      How do you use a TOC, Mel?
      - Mel Choyce 7:08 pm on February 14, 2013
        
        Let’s take a step back for a minute. Design decisions need to reflect our content and our users’ goals and activities.
        
        What content is going to populate these handbooks? Do we have drafts of any of them yet? Does the design even matter yet if we won’t have content to shape design?
        
        How long will the TOC be? If the TOC is too long, sticky isn’t an appropriate choice. Some sort of collapsible panel might be — especially if it takes up horizontal space, not vertical space. (Something like Frank Chimero’s Shape of Design site is an example of an alternate navigation idea that works on desktop: http://www.shapeofdesignbook.com/chapter01.html)
        
        How many of our users will be reading on desktop vs. tablet vs. phone? Our navigation doesn’t need to be the same across devices as long as it is appropriate and intuitive for the tasks users are trying to complete.
        
        What other tasks will they be doing while they’re reading the handbooks? If they’re switching between multiples windows, tabs and programs, then sticky might be good because they’ll always have a clear indication of where they are.
        
        In all honesty, I’m not sure I use a lot of sites—aside from books and the Codex, actually—which include a TOC. With something like a story or a browser-based book, I tend to only navigate linearly. With the Codex, I tend to cmd+f anything I’m looking for or scan headlines.
      - Jerry Bates (JerrySarcastic) 7:39 pm on February 14, 2013
        
        Those are great points, and I think the answer is that the content will vary based on the handbook and it’s intended audience. It sparked an interesting discussion on IRC yesterday (see log) and what is clear is that this design needs to accomodate several different learning styles.
        
        As to how long a TOC can be, this example from @raggedrobins shows that it can potentially be very long indeed! I’m not really a fan of long articles like this, but several people in IRC felt that they were useful depending on the task, as they keep all the steps on one page, avoiding the issue of multiple tabs, jumps, etc.
        
        For sure, a TOC of that size would need to be handled very carefully indeed. 🙂
- Jerry Bates (JerrySarcastic) 6:11 pm on February 14, 2013
  
  @esmi – I am totally with you; I don’t love them either. Lots of feedback from the other two wireframes asking for this, however, which I why I show it here.
  
  I just don’t use a TOC so heavily (as navigation) that I feel the need to see it in my view when I scroll, so personally I think it’s unnecessary, but on really long pages with lots of headings I suppose it could be helpful.
Kim Parsell 6:28 pm on February 14, 2013

If we are going to do a stationary link for the TOC, I would rather see it on the top upper-right part of the page, not the bottom. So many sites have bottom menus that you can’t get rid of. They are distracting and annoying for me. I’m thinking that a simple “back to top” link would be much better.
Pingback: The WordPress Weekend Roundup - WP Daily

Want to get involved?

Weekly meetings

Share this: