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 2:42 pm on February 8, 2016 Permalink |

    HelpHub Meeting Agenda: Feb. 9 

    We’re well underway with development for HelpHub, so this week’s meeting is more of a development status update than anything else. There won’t be any specific agenda other than developers reporting back and seeing if we can set some goals for feature delivery dates.

    Time/date: Tuesday, February 09, 2016, 14:00 UTC in #docs

    We still need to discuss content planning, but that’s still on hold for now as I need to work a few things out on the admin side before we can have any fruitful discussions around it. As soon as things are ready, however, we’re going to dive right into the content structure and planning the articles that we’ll need to write.

  • Hugh Lashbrooke 10:00 am on February 4, 2016 Permalink |
    Tags: status   

    HelpHub Update: 4 February 2016 

    Instead of the weekly meeting recaps I thought it would be more beneficial if I posted a weekly update covering the general status of HelpHub that explains where we’re at and if there are any areas where we could use some additional assistance.

    Current status

    We finished off 2015 with finalising the wireframes for the project and we’re using those as a base for our front-end development.

    We are managing the development of the project through GitHub – project developers are added as collaborators so they can branch and send pull requests with updates. All pull requests are discussed and approved before merge, with all merges being handled by the developer who sent the pull request. Other development guidelines are listed in the repo’s readme file.

    You can check out the repo code and issues as at any time to get a more up-to-date view of the current project status.

    Where you can get involved

    While we have a solid team of individuals working on the development of HelpHub, we’re always happy to welcome others who are keen to contribute. If you would like to get involved then please join us for our weekly meetings on Tuesdays at 14:00 UTC in #docs (note that we might be moving that meeting 30 minutes earlier, but I will confirm that in the meeting agenda post on Monday).

    You are also welcome to fork the HelpHub repo and send in your pull requests. If your work is what we’re looking for then you will be added as a collaborator so you can push directly to the repo itself.

    If you have ideas for how we should be building HelpHub, but you don’t want to (or aren’t able to) do the development yourself then we will always welcome your valuable insight in the GitHub issues as well as in our weekly meetings.

  • Hugh Lashbrooke 12:19 pm on February 1, 2016 Permalink |

    HelpHub Meeting Agenda: Feb. 2 – Assigning development tasks 

    At last week’s meeting we finalised who would be on the development team for HelpHub. This week we’ll be assigning development tasks.

    Time/date: Tuesday, February 02, 2016, 14:00 UTC in #docs


    1. Development task overview
      • I have added various tasks as issues on the HelpHub repo – we need to go through these and add any additional tasks that might be relevant.
    2. Assigning tasks
      • We need to assign tasks to members of the development team so we know who will be working on what.

    Note that I am pushing back the content planning discussion a bit as I still haven’t been able to confirm a few related details for that. We do need to get that discussion started soon though, so I’m shooting for next week to get going on that front.

  • Hugh Lashbrooke 10:59 am on January 27, 2016 Permalink |

    HelpHub Meeting Recap, Jan. 26: Development kickoff 

    Thanks to everyone who was present for the first HelpHub meeting of 2016. It was great to get things going again for the year. Read the meeting agenda and the Slack logs (login required to view chat logs).

    We didn’t actually discuss the content planning side of things, as there were a couple of people who need to be involved there who were unable to make the meeting. We should be hitting that next week though.

    Ultimately what we finalised at this meeting was the development team as well as the development workflow for the project. You will find all of this info on the HelpHub GitHub repo.

    We will be using Underscores for theme base and importing the standard WordPress.org header and footer into it in order to keep things consistent. Aside from that the development flow as well as the project collaborators are listed on the GitHub repo, so you can find out all of that info there.

    Note that next week’s meeting may be 1 hour earlier – I just need to confirm if that will work for the key players before I schedule it, but I will post the agenda (with the meeting time) at least 24 hours before the it starts.

  • Hugh Lashbrooke 2:34 pm on January 21, 2016 Permalink |

    HelpHub Meeting Agenda: Jan. 26 – Kicking off Development 

    It’s a new year and we’ve got a new phase of the HelpHub project to get to work on! At the end of last year we wrapped up the wireframes and they’re looking really solid.

    The next step from here is to get going with development. In order to manage our development in one place, I’ve set up a GitHub repo – it is currently empty, but I will have the barebones structure of things in there by the time we have this meeting on Tuesday.

    Time/date: Tuesday, January 26, 2016, 14:00 UTC


    1. Confirming developers
      • A few people have already volunteered to be involved in development, but I know how plans can change, so let’s finalise those plans for 2016 and confirm who will be digging into the HelpHub code.
    2. Content planning
      • We have yet to put a lot of time towards planning the content of HelpHub (aside from a general idea of knowing what the project is), so I think it would be a good idea to start discussing that more intentionally.

    If you have never put your name forward for HelpHub before, then you are welcome to attend this meeting and throw your name in as well.

    See you all then!

  • Jen 5:45 pm on January 4, 2016 Permalink |
    Tags: annual survey, contributors   

    2015 Contributor Survey 

    Hi docs folks! Thanks for all your hard work and contributions in 2015. Could you contribute few more minutes to fill in the 2015 contributor survey? It will help us establish some baselines around the contributor experience so that we can see how things change over time.

    **This is being posted to all the Make teams, so if you subscribe to a bunch of p2s and keep seeing this post, know that you only need to fill the survey in once, not once per team.**

    The survey is anonymous (so you can be extra honest), all questions are optional (so you can skip any that you don’t want to answer), and we’ll post some aggregate results by the end of January. It took testers 5-10 minutes to complete on average (depends how much you have to say), so I bet you could knock it out right after you read this post! 🙂

    There are two sections of the survey. The first has questions about team involvement, recognition, and event involvement, and is pretty much what you’d expect from an annual survey (which teams did you contribute to, how happy are you as a contributor, etc).

    The second section is about demographics so we can take a stab at assessing how diverse our contributor base is. All questions are optional, but the more information we have the better we can figure out what we need to improve. If there’s some information you’d rather not identify, that’s okay, but please do not provide false information or use the form to make jokes — just skip those questions.

    The survey will be open until January 15, 2016. Whether you have 5 minutes now, or 10 over lunch (or whenever), please take the 2015 contributor survey. Thanks!

  • Hugh Lashbrooke 10:39 am on December 3, 2015 Permalink |  

    Community Summit Working Day: HelpHub 

    As the Docs team, we don’t really have any practical projects to work on as part of the Community Summit Working Day, but I thought it would be useful to see if anyone was interested in doing a bit of work on HelpHub today.

    If you look through the HelpHub category archive you will see that we’re at the stage now where we have wireframes complete and are ready to get going with:

    1. Development
    2. Content planning

    We have volunteers for development and will start planning and working on that in January, so for now it would be great to get a head start on planning the content structure for the site.

    With this being my first Community Summit, I’m not 100% sure how the Working Day is structured, but if anyone would like to be involved in shaping the way that we present and interact with WordPress user documentation then come find me (or ping me on Slack) and we can spend some time working on this together today.

    Given the scope of what needs to be done, I can’t see it taking the whole day, so if you are involved in any other team as well then there will still be plenty of time to work on other projects too.

  • Hugh Lashbrooke 11:06 am on November 26, 2015 Permalink |

    HelpHub Meeting Recap, Nov. 25: Wireframes Finalised 

    Thanks to everyone who chipped in during yesterday’s HelpHub meeting. It was the last one that we will have this year and I’m excited that we have made the progress that we have so far! You can read the full Slack logs here.


    The main purpose of this week’s meeting was to nail down the final wireframes that we are going to be using. We went through the feedback thoroughly and, based on our own ideas as well as the feedback we received, we have finalised these wireframes as the ones that we will be running with. A huge thanks to everyone who contributed their thoughts and ideas to this process especially @saracope and @greensteph for their hard work on the wireframes themselves.

    We will also be adding wireframes for mobile views before we begin development as we will be keeping responsiveness as a priority for v1 of this project.


    After finalising the wireframes we decided that it would be a wholly unnecessary step to create full design mockups for HelpHub, largely because we already have the layout finalised and the actual styling will be based on the rest of WordPress.org, which leaves very little need for actual designs to be put together.


    So the next phase of the project is development. We have a number of volunteers who will be chipping in to help with this for both the front-end and back-end side of things. When the new year starts we will kick off with a discussion regarding the data structure (required custom post types, etc.), which will then inform the architectural decisions for the project. At the same time we will discuss the theming side of things and settle on the way forward for building the front-end of the site. I will look into our options here regarding the use of GitHub and any other related tools that would prove useful, but either way – development of this project will be done in an open and inclusive manner.


    So with that, I’ll leave you all and will report back next year when we kick off with the development phase of this exciting project!

  • 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

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
Skip to toolbar