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

  • 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.

  • Siobhan 11:02 am on January 5, 2015 Permalink |

    RIP Kim Parsell 

    It is with great, great sadness that I write this post. Last weekend, the docs team was struck by some truly tragic news: Kim Parsell, one of our most beloved members, died at home in Ohio.

    Kim has been an integral part of the docs team for the past few years, and to say that she will be missed is an understatement. Kim was such an important part of both the docs team and the wider project. She worked hard to improve WordPress’ documentation, spearheading the inline docs efforts with @drewapicture. She was a Recent Rockstar in WordPress 3.7, and has been a contributing developer since WordPress 3.9.

    But she’ll be remembered for much more than her achievements in documentation and code. The first time I met Kim was at the very first docs meetup in Cincinnati in 2013. The first thought that struck me was “wow, that lady can talk!”. And talk she did: she was open, and welcoming, and big-hearted. She shared so much of herself, and listened when others wanted to share with her. She had such incredible warmth. I will always remember the last time I saw her – when she gave me a tight, tight hug, when we said goodbye in San Francisco. She was a great hugger.

    I hope, that despite our grief, that we can reflect with gladness on the last few years of Kim’s life. She has been part of a community that she loved and that loved her, a community that gave her joy. From her remote corner of Ohio, she made friendships across the world. She flourished in the WordPress community, and became part of something that made her happy. I am proud to have played a small part in her happiness, just as she played a part in mine.

    Kim was not someone to get knocked down easily. She was tenacious, and she was a fighter. So the docs meeting will continue as usual, this Thursday, and rather than letting this knock us down we will keep doing what we do, and in doing so keep her spirit alive.

    RIP Kim. We will miss you.


    • Marcus 1:13 pm on January 5, 2015 Permalink | Log in to Reply

      That’s really sad to hear… whilst I never had any direct contact with her, could not help but come across the various contributions she made that added value to so many people’s lives including myself. Thoughts go out to her family and friends.

    • Jeff Chandler 3:22 pm on January 5, 2015 Permalink | Log in to Reply

      Thank you for everything you did Kim not only to make WordPress better, but making the people surrounding the project better as well. I’ll miss you.

    • Dougal Campbell 4:45 pm on January 5, 2015 Permalink | Log in to Reply

      So sad. I didn’t know Kim terribly well, but we had conversed online, and she was always such an upbeat person. I know she is missed by many.

    • Eric Amundson 7:35 pm on January 5, 2015 Permalink | Log in to Reply

      Thanks for the great post, Siobhan.

      I’m so glad to have known Kim and was always impressed with her humble demeanor, relentless contributions, and driving participation in WP docs. She was a terrific role model, and always patient, helpful, drama-free, and wonderful to work with.

      I can still hear her voice and can’t believe she’s gone. She’ll always be a WordPress Rockstar to me.

    • Graham Armfield 8:23 pm on January 5, 2015 Permalink | Log in to Reply

      This is really sad news Siobhan.

      I never knew Kim, but I did meet her at WCSF in October. She came across as a thoughtful and generous person, happy to share her knowledge and time with anyone.

      A great community is made by such great people.

    • Maria 10:04 pm on January 5, 2015 Permalink | Log in to Reply

      I am so sorry to hear this news. Siobhan, you described Kim perfectly. Her contributions will never be forgotten.

      Thank you Kim for the chance to getting to know you, you will be missed!

    • Timothy Bowers 11:17 pm on January 5, 2015 Permalink | Log in to Reply

      Although I didn’t know Kim, it’s always sad when this world loses the light of truly remarkable and great person. My thoughts are with the friends and family in these sad times.

    • Jose Castaneda 1:31 am on January 6, 2015 Permalink | Log in to Reply

      Really well said, Siobhan! She was a great hugger and greater person for inspiring and motivating others.

    • suzettefranck 4:23 am on January 7, 2015 Permalink | Log in to Reply

      Hello everyone in the docs team and friends of Kim,

      I reached out to Kim’s son, Gary on facebook, and I have set up a website to remember her by at http://wpmom.org. If anyone would like to help or contribute content or photos to this effort, please reach out to me, my email is hello (at) suzettefranck.com or @suzette_franck on twitter or @suzettefranck on Slack.

      I loved Kim and I always saw her being active with WordPress documentation and contributing, but I only met her twice in person, at the last two WCSF, so I am sure there are people that have some wonderful memories of Kim that they would like to share. For now, I am trying to link to all the wonderful posts that people have been putting out so far.

      My mother died a few days before this Christmas, and Kim tweeted me sending me hugs and prayers to my family, which I was deeply touched by since I did not know her super well. When I heard the news that she had passed, I was completely heartbroken, like everyone else, but I wanted to do something to pay tribute to her and I couldn’t find that anyone had started a page, so I did.

      I would love any thoughts or suggestions that anyone has, as you all knew her better than I.

    • Ustimenko Alexander 8:38 pm on February 20, 2015 Permalink | Log in to Reply

      So sad :(

      With sympathy from Russia.

    • Bishoy.A 11:20 am on March 5, 2015 Permalink | Log in to Reply

      So bad to see her go :(

      Condolences from Egypt.

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