Summary for Docs Team Meeting: January 27, 2020

Facilitator: @kulsumsiddique

Attendance: @kenshino, @bph, @felipeelia, @kulsumsiddique, @audrasjb, @ibdz, @wpza, @felipeloureirosantos, @nullbyte, @kafleg, @atachibana, @nobnob

Note-taker: @audrasjb

Next week Facilitator: @kenshino (but invite for other meeting facilitator is open, please comment below if interested)

Team workflow and badges

@felipeelia: workflow docs are being constructed on Trello. @milana_cap is the one to ask for access if needed.

Badges are being discussed in this P2 post. The contributor badge has been discussed for a while now, trying to reach a number of X micro contributions. On his last comment there, @felipeelia suggested to give the badge right away, just as in Core and Meta. @bph added that there is precedent on other teams and make the contributor badge seen right away: it’s the best onboarding tool we have.

@bph proposed a list of elligible contributions:

  • Fix an article
  • Create meeting notes
  • facilitate a meeting
  • reporting an issue on the comment form?
  • Creating a PR for Gutenberg docs
  • user notes on code reference
  • write an article on HelpHub
  • update an article on HelpHub
  • migrate a page to DevHub
  • Report an issues

@kenshino shared some worries about relevancy: “if we say that fixing a typo is fine – we’ll have a rush of requests to do that to farm badges”. Indeed, Core and Meta have automated system to give props to people who contribute on Trac, based on commit messages. There is no such system for Docs.

@felipeelia argued that 1) People receive core/meta badges sending a 1-line patch ; 2) Coming in to Docs Slack team and reporting a small typo does require some effort. @bph added that working out how to communicate a fix to the Docs team is a significant step. even if the contribution is just a typo fix. @kenshino agreed, but the team must keep an eye on abuse to tighten those rules if needed.

Regarding Team Badges, @kenshino proposed to set up a sheet and to give edit access to people that are running projects within the Docs Team.

HelpHub Survey

Reminder from previous meeting discussions: The goal is to build the questions of the survey with the general theme being “How do you think we can improve the WordPress documentation?”. Some questions using the likert scale to track how good it is now so the Team can repeat the survey in the future. Some open fields to get proper feedback so it’s possible to define future projects better. That would be great for this survey to be ready for WordCamp Asia, in less than one month.

@atachibana is coordinating the effort. @bph proposed to assist on this task.

Step 1 is to start a Google Doc in the team’s shared folder.

This survey and the Docs team focus for WordCamp Asia are set to be the next meeting focus.

@bph proposed to draft a P2 post to ask for questions proposals. @kenshino proposed to review this draft.

#contributor-day, #helphub

WCSF Contributor Day

We’ve made plans to work on completing both the developer handbooks during our two day team meetup following WCSF.

I’d like to use this thread to discuss ideas on what Docs tasks we can have contributors work on during Contributor Day on Sunday.

This is a good opportunity to have contributors work on non-handbook tasks that also need to be completed.

A couple possibilities are:

  • Code Reference Migration: migration of content from the Codex code references to the new code reference, including reviewing content, adding examples, and setting up redirects from the Codex.
  • Codex cleanup: review of Codex content – editing, truncating, deleting pages that are out of date.

If you have other suggestions, please add them in the comments. Also indicate whether you’ll be available to work with new contributors on Sunday.

#contributor-day, #wcsf2014

Learned about helping out and getting started with…

Learned about helping out and getting started with documentation this past weekend at WordCamp LA. Edited my first page in the theme handbook and looking forward to digging in some more 🙂 I’m a designer, not a developer, so I’m focusing on clarity and ease of understanding, consistency in formatting, etc.

I do have some questions about formatting for consistency, such as:

  • Sometimes things are capitalized and sometimes the same thing isn’t … so, what should be capitalized and what should not? (i.e. post, page, Post Type, Custom Post type)
  • In a list of items, if not in a bulleted list, do you want the comma used before the “and” or not?
  • In a bulleted or numbered list, should each item have an initial cap or not?
  • And regarding consistency in bolding, should code references (i.e. post_type) use a bold or regular style?

I’m sure I’ll have other questions as I go, but I’m looking forward to digging in, reading all your hard work, & learning! Oh, and please let me know if I do something wrong or mess anything up … just a little nervous about getting started 🙂


I’m at WordCamp LA Contribute day We’re looking…

I’m at WordCamp LA Contribute day. We’re looking over pages and cleaning up typos and language (not finding many problems) I’ve been looking at pages for The Loop, Theme Functions, etc


Contributing this fine WordPress Weekend

There are two events particularly relevant to the docs team coming up this weekend:

WP Contributor Day in Manchester, UK

The newly formed WP Contributor Day group is running their first event on March 1st from 10AM – 6PM UTC, @johnbillon has written a post with more details. The event’s site is at

For docs folks in particular, if you’re in the north of England, why not head on over? It’s sure to be a great day, whatever your skills or experience level.

If you’re elsewhere, and already familiar with contributing then joining in virtually via #wordpress-sfd would be a fantastic thing to do.

Monthly Docs Sprint in Seattle, USA

The Seattle Meetup group are hosting their monthly Docs Sprint on Saturday, too. It’s running from 10AM – 2PM PST.

It’s been a while since we’ve mentioned the additional virtual nature of these sprints here on the blog, so for the benefit of newer contributors, here’s some of the backstory.

In short: the meet-up group welcomes your participation, wherever you may be!

To quote @sewmyheadon, here’s what do to if you’re not in the Seattle area:

Online: If you’re bashful, or simply outside of the Seattle area, you can simply logon to the IRC channel at #wordpress-sfd and participate from anywhere.

Why not take a peek at the getting started page for the handbooks to gather inspiration for your contributing this coming weekend?

Happy weekend, docs!


Handbook Tasks – WordCamp Sofia Contributor Day 2013

Howdy WordCamp Sofia Contributors!

Thanks a bunch for helping with WordPress documentation – we all really appreciate your help!

We’ve been focusing a lot on the Theme Developer Handbook and Plugin Developer Handbook, which both need a good deal of work.

For most people, the toughest roadblock to contributing is just getting started, so hopefully this will help.

Where to Go

The jumping off point for all docs-related efforts is: – In the sidebar, you’ll see links to the Handbooks along with the Spreadsheets we use to track their progress.

  1. The Theme Developer Handbook is at:
    • . . . and the spreadsheet that we use to track Theme Developer Handbook progress is at:
  2. The Plugin Developer Handbook is at:
    • . . . and the spreadsheet that we use to track Plugin Developer Handbook progress is at:
  3. The IRC channel we use is at #wordpress-sfd on Freenode.
    • This is a great place to ask questions, post links to docs for review, and cheer each-other on.

Getting Started

If you haven’t already, you’ll want to:

  1. Read the Handbook Style Guide
  2. Review the Handbook Tutorial Template
  3. Find a topic in the Theme or Plugin developer spreadsheet that interests you
  4. Check the Needs column of the spreadsheet to see if there are specific things that are needed in this document
  5. Add your name to the Responsible column in the spreadsheet
  6. Write or edit in HTML or Markdown and give it to Mario Peshev or email it over to me at eric [at] and we’ll post for you.

What if I’m not a Writer?

If you’re not comfortable writing or editing, you can also help by:

  • Creating code snippets for examples
  • Taking relevant screenshots
  • Reading existing documentation and making comments regarding improvements

If you’re completely overwhelmed and not sure where to start, you might start by reading through the Handbook and, when you’ve got questions, find missing content, or see improvements, please feel free to work on the document, or make comments in that document’s comment section.

I’m here to help in any way I can, so feel free to ping me (@sewmyheadon) or Mario (@no_fear_inc), or post to the #wordpress-sfd IRC channel if you have any questions.

Thanks again and have a great WordCamp!

#contributor-day, #docs, #wcsofia

Inline Docs Tasks – WC Sofia Contributor Day 2013

For those of you contributing to Inline Docs during Contributor Day Sofia 2013, we thank you. 🙂

The Inline Docs initiative is a part of the overall effort to build a new code reference that will live at Creating inline documentation for hooks will provide the information necessary to populate that portion of the code reference.

What You Need To Know

Please read the PHP Documentation Standard section on documenting Hooks (Actions and Filters) to familiarize yourself with how the actual doc block should be formatted, and how duplicate hooks should be documented.

  • The Documenting Tips section covers recommended language when writing descriptions, as well how to determine the version for @since, and guidelines for Code Refactoring.
  • The Formatting Guidelines section covers how to format the text in the descriptions.

Opening A Ticket > Getting Started > Trac Preferences explains how to log in to Trac with your username, and how to configure your email address in Trac preferences so that you receive Trac ticket notifications.

Working With Patches covers creating patches using the command line and TortoiseSVN (for Windows users). If you are using Git, please follow the creating patches guide at Contributing to WordPress Using Github by Scribu.

How to Contribute

We have reserved 15 files for the WC Sofia contributors to work on, and have tagged them (Reserved-WC Sofia) on the Add Inline Docs for Hooks post. The files are:

  • wp-admin/network/edit.php
  • wp-admin/network/settings.php
  • wp-admin/network/site-new.php
  • wp-admin/network/site-settings.php
  • wp-admin/network/users.php
  • wp-admin/user/admin.php
  • wp-admin/includes/export.php
  • wp-admin/includes/menu.php
  • wp-admin/includes/template.php
  • wp-admin/includes/theme.php
  • wp-includes/functions.wp-scripts.php
  • wp-includes/functions.wp-styles.php
  • wp-admin/press-this.php
  • wp-admin/update.php
  • wp-admin/user-edit.php

The following are the steps you need to follow:

1. Leave a comment on the Make/Core post with the name of the file you are going to work on.

2. Update your local WordPress SVN or Git repo (use git pull) to the latest version of WordPress trunk (currently 3.8-alpha).

3. Create a new ticket on Trac for the file.


  • Format the title as “Hooks Docs: path/to/file.php”.
  • The Type should be “defect (bug)”.
  • Assign the ticket to the “Inline Docs” component.
  • Leave the Version blank.
  • The Severity should be “normal”.
  • Add your username or email address to the CC: field so you’ll receive activity notifications for your ticket.

4. Edit the file, and make a patch. Please make sure you create the patch from the root directory of your WordPress SVN or Git checkout.

5. Upload your patch to the Trac ticket you created, and add the keyword “has-patch”.

Patch Review Process

1. We will review your patch, and may make recommendations for changes that need to be made. We will change the ticket keyword to “needs-patch” if changes are needed.

2. Please read the review, ask for clarification if needed, then make the requested changes, and create a new patch.

3. Use the same filename for your revised patch, and upload it to the ticket. Remove the “needs-patch” keyword, and add the “has-patch” keyword.

  • Note: Do not check the box next to Replace existing attachment of the same name – it is preferred to have copies of all attachments submitted to preserve the history of the ticket. Trac will automatically append an incremental number (xxxxx.2.diff) to the end of a patch filename to prevent an accidental overwrite of the existing file, in cases where the same patch is submitted multiple times due to needed changes.

We will review the updated patch, and may request further changes, if needed. Repeat steps 2 and 3 until we say your patch is good, and we tag it as “commit”.

Congratulations, and thank you for contributing to WordPress! 🙂

#contributor-day, #inline-docs, #wcsofia

WordCamp Providence Contributor Day

Here are some tasks from the Theme Dev Handbook that can be carried out on docs at the Contributor Day at WCPVD:

Need to be written:

  • Media:
  • Post Thumbnails:
  • Theme Security:
  • Theme Options:

The following pages need to be expanded:

  • Theme Customizer:
  • Custom Headers:

The following pages need to be reviewed and edited:

  • Internationalization and Localization:
  • Pagination:
  • Comments:

The following will come in useful: