Make WordPress Documentation

Welcome to the official blog for the WordPress documentation team.

This team is responsible for all things documentation, including the Codex, handbooks, developer.wordpress.org, admin help, inline docs, and other general wordsmithing across the WordPress project.

Want to get involved?

Join the discussion here on the blog, or check out the landing pages for:

Weekly Meetings

As well as discussing docs issues here on the blog, we use Slack for group communication.

The team holds weekly office hours on Thursdays from 18:00-19:00 UTC in the #docs Slack channel.

Individual teams have their own regular meetings – you can find details of those in the sidebar.

Recent Updates Toggle Comment Threads | Keyboard Shortcuts

  • Hugh Lashbrooke 11:00 am on November 24, 2015 Permalink |

    HelpHub Meeting Agenda: Nov. 25: Wireframes decision & design plan 

    Please note that this week’s meeting is moved to Wednesday again (same time of course – 14:00 UTC).

    A huge thanks to everyone who gave such valuable feedback on the wireframes – your input is invaluable and will help us to make properly informed decisions about the best way forward with this project.

    This week’s meeting will be about deciding on the final wireframes and then looking at the next steps from there.

    Time/date: November 25, 2015, 14:00 UTC


    1. Wireframes
      • We will look at the feedback and decide on the final wireframes that we’re going to be using
    2. Design plan
      • Now that we have the wireframes in place, let’s chat about the design process

    This will most likely be our last meeting for the year – I’ll be at the Community Summit next week and moving house after that, so once we’ve made some decisions in this meeting we’ll agree to reconvene in early January to continue.

  • Hugh Lashbrooke 12:29 pm on November 19, 2015 Permalink |
    Tags: feedback-needed,   

    Feedback needed on HelpHub wireframes 

    Hey everyone,

    At yesterday’s HelpHub meeting we nailed down the final wireframes for the front page and the single articles. The other pages (search results & archives) will come later and will be largely informed by wireframes of the pages that we already have, so I’m not too worried about them.

    What we need now is feedback from the broader community, which is where you come in :)

    You will find the wireframes up on Balsamiq where you can view and comment on them without having to login. To give a bit more context for what you see there, we have three options for the front page:

    • Home page 1
      • Focussed search box and category boxes
    • Home page 2
      • Focussed search box, less category boxes and boxes for user skill level with a curated list of links (dubbed ‘learning paths’)
    • Home page 3
      • Focussed search box, tabbed box for learning paths and a few category boxes

    Then, alongside that, we have two options for the single article pages:

    • Single article 1
      • Clean layout with focus completely on the article and related links pushed to the bottom
    • Single article 2
      • Related links in the sidebar for quicker access

    Don’t worry about the design at all – these are just wireframes, so we’re looking at the layout here and not the design.

    What we need from you

    So with all that info in mind, what we’re looking for at this point is feedback on which wireframes you think are more effective at delivering a great site for user documentation. You can leave comments on this post or directly on the wireframes, but either way – it would be awesome if we could have some feedback of what you all think of them and if you think we’re hitting the right mark.

    Huge props to @saracope, @greensteph and @versatility for their hard work on these wireframes!

    • Hugh Lashbrooke 11:00 am on November 24, 2015 Permalink | Log in to Reply

      Thanks so much to everyone for the invaluable (and thorough) feedback. We’ll be meeting tomorrow to decided on the final wireframes based on all of your input – feel free to join us! https://make.wordpress.org/docs/2015/11/24/helphub-meeting-agenda-nov-25-wireframes-decision-design-plan/

    • Nirav Mehta 6:14 am on November 23, 2015 Permalink | Log in to Reply

      I’m sure a lot of thought has gone into making these wireframes. Here’s my feedback:

      1. I like categorization by topic, but definitely not by skill level. Most beginners will start reading category sections and follow what appeals to them. Most intermediate / advanced users will simply search (or rely on Google to bring them to the correct page.)

      2. I didn’t see it in the wireframes – and guess it must be planned – but including screenshots in SP will be a great help to beginners. They are hard to maintain but very useful.

      3. Another thing that can make SPs more usable is to follow “task centered” writing style.. Guiding people step by step. And making sure they have a sense of achievement at the end. (I would also remove the “time to read” at the top btw)

      4. For the homepage, I’d split it into three columns. First two showing static content by categories. Third showing dynamic content. So it’s more like HP2, but merging the two content sections and putting them in columns rather than rows.

      5. For SP, the sidebar is important, but I think it should show up only after a few seconds on the page. Let the user get a grasp on content on this page. And offer additional content after 3-4 seconds for broader navigation.


    • Marius (Clorith) 12:21 pm on November 22, 2015 Permalink | Log in to Reply

      I’m going to be the one heading against the current here, and say the idea of Home page 2 is more future proof, constantly trying to manually keep track of what people need the most is a daunting task with such a large ecosystem, an automated feature for this would be much better, and would be able to pick up new elements much better than any individuals could.

      I do agree with Justin that the user skill labels are bad for the curated list, so rethinking that section would be ideal, but I still think the dynamic content first is the way to go.

      Home page 3 is just terrible, tabs are the bane of my existence (I dislike the UX of tabs, and I die a little inside every time I’m forced to use them :( )

      Single articles! #1 please, given the layout of the rest of .org (with the exception of handbooks, the layout of which I also think could be improved upon) there’s not really a whole lot of screen real estate when it comes to the width, we’d either want to increase the width for readability, or drop any side navigation like this.

      Having the “was this helpful” after the article makes sense, that’s where you’d expect to find it, after reading it and deciding if it was or wasn’t helpful.

      Home page #2
      Single page #1

    • Lorelle 6:43 pm on November 19, 2015 Permalink | Log in to Reply

      Fantastic work. Simple, clean, and focused on the user.

      I’m with the majority here as well, good company. My reasons, however are a little different.

      I’m torn between HP1 and HP2, but let me start on why I like those two layouts in general.

      They most resemble the long tested and experimented with Codex front page, a layout we found to work over many years of testing. The familiarity will help with the migration of users.

      It is a clean, simple, and easy to access and navigate portal to the information people need, which is also why I’m torn between the two. We did extensive testing to decide which links to put on the front of the Codex to direct people to core information, then it remained static, rarely updating, locked down hard due to attacks as well. Still, the relevant information continues to be the information most people seek.

      Yet, trusting the crowd to determine what is the most popular information and allow it to shift and move with trends is also important. If there is a sudden burst of security issues, documentation related to those should move to the top with their popularity, same with any major change to WordPress.

      I’m sure it’s been considered but I think an experiment with the links in each section fixed for the first 1-3 links in the list to the most popular or support-centric for that category is ideal, and the last links in the list be set to generate based upon popularity and demand.

      A sidebar in the single post pageview is an absolute MUST in neon red letters. Offering related content is not only helpful, it is critical to ensure broad usage. People often don’t know what they are looking for because they don’t have the names, and this broadens their likelihood of finding the help they are really looking for.

      As for the voting, up and down makes me crazy. It is too easy to ignore or abuse. Yes, No, Maybe, Needs More Information, or something like that would be a better list to help not only improve the documents based upon these results, but also to improve the analytics and metrics as a result.

      I’m also with @Andrew. The wiki-style table of contents for longer articles is very important to let people jump down to the exact help they need. If there is a length limit on the docs, then it isn’t as important, but if there isn’t, then this would be essential.

      Again, great work!

    • Jay Hoffmann 5:58 pm on November 19, 2015 Permalink | Log in to Reply

      I’d opt for Homepage 1 as well. I think getting to “Beginner”, “Intermediate” and “Advanced” would be incredibly difficult, because there are different use cases for each. Beginner developer or user for instance. Homepage 1 surfaces the popular content, and relies on search to do the heavy lifting.

      I’m leaning towards Single Page 1, but most people seem to be into version 2, and I can see that.

      These are great!

    • Julie Kuehl 3:07 pm on November 19, 2015 Permalink | Log in to Reply

      I like Homepage 1 and Single Page 2.

      I don’t like “Beginner”, “Intermediate”, “Advanced”. They can be so arbitrary, and also off-putting. For myself, I find a numeric “Skill Level 1” to be a bit more objective, and possibly more descriptive, if you need to describe the content. If people need more background information to understand the page, hopefully that would show up in the Related Articles links. (Think prerequisites.) FWIW, YMMV.

    • mangopeargroup 1:51 pm on November 19, 2015 Permalink | Log in to Reply

      I would agree that homepage 1 is the best of the homepages – consistent over dynamic links would be better for returning users I feel.

      Regarding the single pages, I would move the sidebar to the right and add a table of contents, as Andrew mentions above, for long articles.

      I would also suggest moving the article rating to below the tags instead of in the sidebar as the sidebar is all about sending users to another page/section but the article rating is, obviously, specific to the article itself. As I was scanning the SP1 I missed the rating feature because of this.

    • J.D. Grimes 1:37 pm on November 19, 2015 Permalink | Log in to Reply

      I second everything that @justingreerbbi said. HP1 and SP2.

    • Matthew 1:35 pm on November 19, 2015 Permalink | Log in to Reply

      I agree with @justingreerbbi. I liked home page 1 and single page 2 best. Home page 2 wasn’t that bad although I like the layout of home page 1 better. As for the single pages, number 2 is much cleaner and nicer looking.

    • fevered 1:32 pm on November 19, 2015 Permalink | Log in to Reply

      I like Home Page 1 and Single Page 2 the best. Home Page 2 is a close second but I feel like having theme and plugin help when you get to the front page is more important.

    • Andrew 12:46 pm on November 19, 2015 Permalink | Log in to Reply

      For long articles, can there be a table of contents? It’s useful to guide people to certain parts of the article so that they’re not overwhelmed.

    • Justin Greer 12:43 pm on November 19, 2015 Permalink | Log in to Reply

      Swamped at the office and missed the meetup :(. First off, awesome job of the diversity of the wireframes! Taking a look at the wireframes, I am a big fan of simple stupid when it comes to information and delivery.

      I personally see HP1 being the best fit. The layout is simple yet directive and everything is called out as a category or section. I do not like HP2/3 because I don’t believe that labeling based on user skill is helpful enough to make prominent. Even with advanced documentation elsewhere, there is no categorizing by user level since user skill level does not have defined lines.

      Looking at the SP’s wireframes, I have to go with the sidebar nav. I now a goal is to have simple and clear but lets not get to far from the fact it is a documentation handbook at its core. Maybe a combination of SP1 and sSP with the use of a reading function. My vote is for SP 2.

      My Thoughts
      Homepage 1
      Single Page 2

  • Hugh Lashbrooke 12:06 pm on November 16, 2015 Permalink |

    HelpHub Meeting Agenda, Nov. 18: Finalising wireframes 

    Note that this meeting has been moved 1 day later than usual and will be on Wednesday 18 November this week at 14:00 UTC.

    This week’s meeting will revolve around finalising the wireframes that we went over in the last meeting. I would like to get these 100% final and ready for community feedback ASAP.

    Time/date: November, 18, 2015, 14:00 UTC


    1. Wireframes
      • This is pretty much all I really want to chat about this week, so it would be great to hear from @saracope @versatility and @greensteph about the progress there.

    I’m happy to chat about anything else related to the project that is worth discussing at this point, but the wireframes are the priority right now.

    • Hugh Lashbrooke 3:55 pm on November 16, 2015 Permalink | Log in to Reply

      Everyone note that the HelpHub meeting this week is on Wednesday instead of Tuesday, so it is one day later than usual. It will be at the same time though :)

  • Hugh Lashbrooke 12:22 pm on November 10, 2015 Permalink |  

    This week’s HelpHub meeting is cancelled 

    Sorry for the late notice, but due to unforeseen circumstances, this week’s HelpHub meeting is cancelled.

    We are currently in the wireframing stage of the project and that is coming along well. I am hoping to have final wireframes ready for community feedback from next week thanks to the talents of @saracope @versatility and @greensteph who are collectively putting together some great work.

    Chat to you all next week!

  • Hugh Lashbrooke 12:14 pm on November 2, 2015 Permalink |

    HelpHub Meeting Agenda, Nov. 3: Wireframe report and content discussion 

    As discussed in last week’s meeting, we will be moving our weekly chats one hour later due to daylight savings coming to an end, so we will be meeting at 14:00 UTC instead.

    This week’s meeting will include a report on the wireframes that we spoke about last week and we will also chat about the next steps with the content planning.

    Time/date: November 2, 2015, 14:00 UTC


    1. Wireframe report
      • Let’s look at what has been so far and if it is the right direction for the project.
    2. Content planning
      • We haven’t done a whole lot in this regard yet (aside from the user personas), so let’s start discussing it properly.
    3. Open floor
      • Anything else relating to the project that you think should be discussed?
  • Hugh Lashbrooke 9:54 am on October 29, 2015 Permalink |

    HelpHub Meeting Recap, Oct. 27 

    In this week’s HelpHub meeting we focussed on kicking off the wireframe building process. The discussion was very fruitful and you can see the Slack logs right here.

    The main thrust of the chat was to get started with the wireframes and in order to do that we threw around some examples of current knowledge base sites that we like. These will act as the base for out design inspiration, but we will still be building something completely unique. So, with that in mind, here are a few examples that we discussed – if you have any more that you think are worth taking note of then please add them in the comments:

    Much like the Namecheap example, we are wanting to build something that highlights the search box on the home page with perhaps a few additional helpful links below it, but the main thrust of the home page is that is to be minimal and as search-focussed as possible.

    Note that while design does definitely rely on content (especially for a site like this), we don’t want to hold up the wireframe process while we wait for the content structure to be more established, so we would rather start with building the wireframes ASAP and then revise them as we have a more solid idea of the content we will be working with.

    If you have any feedback or thoughts on any of this then please post that here or in the #docs channel on Slack so we can keep the conversation open.

    Also, see the project page for details on how to view/contribute to the wireframes.

    I’m tagging the individuals here who are going to be working on the wireframes, but this is open for anyone to give their valuable input into: @saracope @versatility @greensteph

  • Hugh Lashbrooke 2:02 pm on October 26, 2015 Permalink |

    HelpHub Meeting Agenda, Oct. 27: Catch up and progress report 

    After 2 weeks off due to the Automattic Grand Meetup, I’m back online, so we can get the HelpHub meetings going again. This week we will be catching up with the people involved in content planning and design, although I don’t think there’s been a huge amount of progress in the last couple of weeks due to general busyness.

    Time/date: October 27 2015 13:00 UTC

    Meeting focus: Catch up and progress report


    1. Current status
    2. New volunteers?
      • A few people have contacted me directly to ask about getting involved so now’s the time to put your hand up!
    3. Next steps
      • I really want to kick things into gear regarding wireframes, so let’s talk about getting that process properly started
    4. Open floor
      • Anything else you want to discuss regarding the project?

    See you all there!

  • Drew Jaynes 5:18 pm on October 15, 2015 Permalink |

    Docs Chat Agenda, Oct. 15, 2015 

    Here’s the agenda for today’s Doc Chat in the #docs channel on Slack.

    Time/Date: October 15 2015 18:00 UTC:

    1. Contributor Day Docs – We’ve had multiple requests for documentation on actionable steps for contributor days. Let’s make a plan.
    2. Project Updates
      1. Theme Developer Handbook – @thoronas
      2. HelpHub – @hlashbrooke
      3. Codex Migration – @drewapicture
      4. Inline Docs – @drewapicture
    3. Open Floor – Have something you’re looking for feedback? Bring it up and let’s chat about it.
  • Hugh Lashbrooke 4:55 am on October 13, 2015 Permalink |  

    No HelpHub meeting this week (or next) 

    Due to me being at the Automattic Grand Meetup this week (and then traveling home next week Tuesday) there will be no HelpHub meeting this week or next. We will pick the meetings up again the following week on Tuesday, 27 October, 13:00 UTC.

    In the mean time, those of you working on the wireframes and content structure can carry on doing that based on the user personas that we chatted about last week.

  • Hugh Lashbrooke 1:45 pm on October 7, 2015 Permalink |

    HelpHub Meeting Recap, Oct. 6 

    In yesterday’s HelpHub meeting we spoke mostly about user personas as a starting point for our content structure and design. You can read the full Slack logs here.

    My apologies for having to leave the meeting early – an emergency came up on my side, but thanks to @samuelsidler for stepping in to help guide the discussion to the end.

    After much discussion (and some initial confusion) we nailed down the user personas we’ll be focussing on. The user personas are effectively the identities of the people who will be using HelpHub. We put our outline together in this Google Doc, but this is what we settled on:

    1. Publishers
      • People who work within a WordPress Installation
      • Content creators, authors, publishers & editors
    2. Maintainers
      • People who install WordPress
      • People who maintain WordPress sites

    Note that we did not include developers as they would largely be redirected to DevHub.

    Inside each of the personas there will also be three levels of experience: Beginner, Intermediate and Experienced. There will obviously be some crossover in the content with regards to the personas, but that’s normal and expected.

    Next steps

    The next steps from here are to start planning the content for each of the personas as well as to start working on the wireframes with the personas in mind. That will be the work for the next little while, so the next few weekly chats (13:00 UTC on Tuesdays) will be updates on the progress there.

    The info on how to get involved, as well as where we’ll be doing the work, are all on the HelpHub project page.

    Feedback needed

    We would appreciate feedback on the user personas from the Docs & Support teams, so if you have any input on that side of things please comment on here.

compose new post
next post/next comment
previous post/previous comment
show/hide comments
go to top
go to login
show/hide help
shift + esc