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

  • Ian Dunn 4:24 pm on July 8, 2015 Permalink |
    Tags: wordcamp.org   

    Better WordCamp.org Docs 

    Hey everyone, over on make/Community we’ve been discussing ways to address the major pain points that WordCamp organizers have with WordCamp.org, and one of those ways is to improve the documentation.

    I just published a post outlining the problems and some potential solutions and I’d love to get feedback from the Docs team on it.

    If you have any thoughts or suggestions, please join the discussion on that post :)

  • lizkaraffa 7:13 pm on May 21, 2015 Permalink |
    Tags: , THB, Theme Developer Handbook, Trello, WordPress   

    Theme Developer Handbook Status Report 

    A lot of activity has been happening in the THB lately. We’re migrating away from the spreadsheet which is pretty unapproachable and overwhelming to contributors and utilized Trello to help us finish the THB. We’ve got about 70% of the spreadsheet migrated.

    In the navigation above under “Handbooks” you’ll notice that the spreadsheet has been deprecated and there is a new menu item called “Contribute to the Theme Developer Handbook.” This item will take you to the trello board.

    Now that we have our new system in place, we’re in need of contributors! If you know of anyone that is interested in helping out please point them to the trello board. There are instructions on how to gain access to the appropriate sites and a step by step guide on how to contribute.

    We are putting the tutorial side of the THB on hold until v 1.0 ships. All tutorial sections are housed on this page until we can reintegrate it with the THB. This setup will allow us to create a consistent and full step by step guide. Additionally, any usable material that is getting cut out of the THB is going onto this page in case we need it in the future.

    We also are doing weekly google hangout meetings on Wednesdays from 12-2pm PDT to offer any training on trello, questions on contributing, and setting aside a time to actually work on the THB. Feel free to join us!

    There is also a meetup in the Seattle area and one in South Sound which you can checkout.

    In a nutshell:

    Please please contribute! :) Also, we welcome any feedback on the contributing process. Please reach out to @lizkaraffa or @sewmyheadon over slack with your comments/suggestions/pain points/etc. Thanks!

  • Siobhan 11:04 am on April 1, 2015 Permalink |

    Emoji in the Codex! 

    Currently the new emoji in WordPress 4.2 aren’t documented anywhere. I found this very confusing when trying to figure out how to use them. This is a great time to get rid of the old Using Smilies page and have a new user-facing emoji page.

    This needs to be done asap so we can include a link to it in the new release.

    The page should contain the following:

    1. Short intro to emoji
    2. Short section on emoji on mobile
    3. Short section on emoji on desktop (including the shortcuts on each platform to bring up the emoji popup)
    4. List of common emoji/smilies

    Anyone interested in volunteering? We need it pretty quickly so we can add a link to it in 4.2.

  • lizkaraffa 9:00 pm on March 12, 2015 Permalink |

    Meeting notes #docs office hours 3/12 regarding THB

    1. Discussed how the THB has great content, but starting at Ch. 3: Theme Functionality until the end of the THB, many sections need more explaining and work to be user friendly for new theme developers and to match the tone started in the first two chapters
    2. Actionable items will be added to pages that need updating. Standardized from here out users creating notes in spreadsheet will include their name and the date of the note to assist in the process.
    3. Inconsistencies between linking to outside references versus including all content within the THB were discussed. A decision was reached to keep everything internal and remove links to non-wordpress.org sites.
      • The problem of long pages was discussed in moving everything internally and the solution was provided to expand/contract code references. @siobahn will create a ticket.
    4. The difficulties in having both a tutorial and reference combined in one handbook was discussed and a shortcode solution to wrap tutorial sections in was decided upon.
      • The styling will be light purple with a hammer dashicon @samuelsidler is creating the ticket
      • Users will be able to hide or expand all future tutorial sections based on their needs
      • Additionally, pulling out the entire tutorial into one combined page/section should be available with the use of the shortcode.
    5. To assist users in the tutorial, hyperlinks to previous tutorial sections will be provided in each new section for users that are jumping in mid process.
    6. A slimmed down version of twenty fifteen theme was decided upon to be the theme built in the THB. Someone to simplify twenty fifteen has yet to be determined
    7. New tasks will be added to spreadsheet that encompass overall goals to be completed by one or two people for the sake of consistency.

    Action items:

  • lizkaraffa 3:18 pm on March 12, 2015 Permalink |

    Okay everyone, Here is the agenda for today’s THB discussion during docs office hours.

    Overall state of THB

    Overview of Inconsistencies

    • Somewhat opposing jumps between tutorial and reference guide
    • Linking to resources externally or keeping it within

    Tutorial Sections

    Problem pages

  • Siobhan 5:17 pm on February 17, 2015 Permalink |

    There’s not a whole lot happening in docs at the minute so how about folding the Handbooks chat in with the docs chat and having a regular docs chat on Thursdays from 18:00 – 19:00 UTC?

  • Jenny 10:14 pm on January 26, 2015 Permalink |
    Tags: community-hub   

    A reminder for those who haven’t seen it.

    Please take a few minutes to fill in the Community Hub Poll as the poll closes Thursday at 00:00UTC.

    For more information on the Community Hub, please check out this post.

  • Siobhan 9:12 pm on January 16, 2015 Permalink |

    Remembering Kim 

    The project is going to be offering an annual travel scholarship in Kim’s name. This is a really fitting way to remember her, giving other people the same joy that she felt through her participation in the community. You can read more about it here: https://make.wordpress.org/community/2015/01/15/remembering-kim-parsell/

    Thanks to @jenmylo, @matt, and everyone else who was involved in arranging it.

  • Siobhan 12:27 pm on January 14, 2015 Permalink |
    Tags: helphub   

    Kicking off helphub 

    Helphub is a new docs/support/meta project. If you’d like to be involved, you can read and comment on kick-off post here and read the full specifications here.

  • Siobhan 4:53 pm on January 13, 2015 Permalink |
    Tags: information architecture   

    Docs Information Architecture 

    I’ve split the types of people who’ll be approaching the content into two broad groups:

    • Users: anyone who uses WordPress, from amatuer bloggers to people setting up a complex multisite installation. WordPress users are a very broad group.
    • Developers: anyone who extends WordPress, i.e. with plugins and themes (or the JSON REST API in the future).

    Below is a diagram which outlines how I envisage the content in the Codex being split up:


    I’ll go through each of these sections.



    Priority: High

    Goal: to provide WordPress users with a searchable database of answers to common questions.
    Target Audience: WordPress users of all levels and ability.
    Example content

    • How do I add an image?
    • How do I activate multisite?
    • How do I add a new user?
    • Can I change my domain?
    • How do I move my plugins folder?
    • How do I increase my PHP memory limit?
    • What is a permalink?

    Status: Helphub spec in draft. To be published soon.


    Priority: Low
    Goal:To provide barebones guides to specific use-cases for WordPress
    Target Audience: WordPress users of all levels and ability, though each individual guide will be tailored towards a specific user level (for example, blogging will be less advanced than the multisite guide
    Example Content:

    • Admin Guide
    • Multisite Guide
    • Installation Guide
    • Blogging Guide
    • Troubleshooting Guide


    The blog can be used for release-related documentation or guides relating to a specific event. For example, whenever we anticipate an issue with a release we will publish an article in the Codex. The blog will provide a platform for that.



    Code Reference

    Priority: High

    Goal: to provide WordPress developers with an automated code reference that includes explanations and user-submitted examples
    Target Audience: WordPress developers of all levels and ability.
    Example content

    • Function Reference
    • Class Reference
    • Hook reference

    Status: Live. Still actively developed.


    Priority: High

    Goal: to provide WordPress developers with guides to extending the platform
    Target Audience: WordPress developers of all levels and ability.
    Example content

    • Theme Developer Handbook
    • Plugin Developer Handbook
    • Intro to developing with WP (including WordPress basics, setting up dev environment)


    • Plugin Developer Handbook – v1
    • Theme Developer Handbook – being worked on
    • Intro to Developing with WP Handbook – not yet started


    Priority: Low

    Goal: to provide WordPress developers with resources
    Target Audience: WordPress developers of all levels and ability.
    Example content

    • Dashicons
    • Other tools

    Status: Dashicons live.


    A blog for publishing useful information for developers, for example information they need to know about a new release, or about changes to developer.wp.org.

    • Mike Schinkel 5:07 pm on January 13, 2015 Permalink | Log in to Reply

      “In the wild” I often see people refer to themselves as “WordPress Developers” who install sites and then install and configure themes and plugins, but who do not actually write any code. So we’ve been avoiding the term “developer” and instead using the terms “WordPress Site Builders” for people who build sites and “WordPress Themers” for people who write mostly write HTML+CSS with some PHP/jQuery sprinkled in, and “WordPress Coders” for people who write PHP/MySQL/Javascript code and build plugins. Something to consider?

      • Siobhan 7:48 pm on January 13, 2015 Permalink | Log in to Reply

        That could get rather complicated when putting together an information architecture for documentation. When we’re breaking down such a large amount of data at the top level it makes sense to break it down into the broadest ways that WP is used.

        Besides, we already have developer.wordpress.org, and wordpress-coders.wordpress.org doesn’t work quite so well :)

        • Ipstenu (Mika Epstein) 9:53 pm on January 13, 2015 Permalink | Log in to Reply


          We could get really nitpicky and point out that WPCOM users are WordPress Users, but they’re user- (they can’t install plugins but they can configure them). We have to start somewhere simple if we want to have a hope of going anywhere.

    • Gary Jones 9:25 am on January 14, 2015 Permalink | Log in to Reply

      Any consideration of having the PHP (code and inline docs), JS and eventually CSS / Sass coding standards moved to developer.wordpress.org/resources? They are currently in the core handbook, but are for, and used by, plugin and theme developers too. They should be a community resource that core, as a member of the community, also try to adhere to.

      • Siobhan 12:25 pm on January 14, 2015 Permalink | Log in to Reply

        I can see the virtue in having them in both places, but obviously we don’t want to keep them in two places as we have to maintain them twice. Let me ask around and see what other people think.

        • Gary Jones 1:34 pm on January 14, 2015 Permalink | Log in to Reply

          I’d rather see them just in the developer resources section, and a signpost left in the core handbook that expresses “Hey, core generally follows the community code standards, which you can find _here_, but core has the following differences: …”

    • Normalize 5:50 pm on January 14, 2015 Permalink | Log in to Reply

      Hi, I’m new, but I want to help. (I’m also on slack.) I’ve done a lot of tutorials for users of my own sites, so hopefully there’s a place to put that to use.

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