Tag Archives: handbooks

Estela Rueda 12:00 pm on November 4, 2025
Tags: contributor recognition, handbooks, new ideas   

Rethinking Contributor Recognition in Documentation Team

At the Documentation Team meeting on October 21, 2025, we started an important conversation: How do we properly recognize contributions and how do we create clear paths for people who want to contribute once, versus those who want to grow into long-term team members?

This discussion surfaced everything from value perception, to badges, to long-term career benefits. Below is a summary of the key questions we’re exploring as we refine a contributor journey that is fair, motivating and future-proof.

What counts as a “valued” documentation contribution?

Not all contributions have the same impact — and contributors know it. We acknowledged that fixing a small typo is not the same as drafting or updating full documentation for a new feature. But where do we draw that line clearly?

We need to define:

  • What is considered a regular (ongoing/essential) contribution?
  • What is considered noteworthy — something worthy of highlight in a release announcement?
  • How do we document these contributions for transparency?

Recognition systems: Props, badges, highlights… or something new?

We asked ourselves:

  • Badges are still meaningful, when should we provide the docs contributor badge vs the docs team badge?
  • What’s the difference between props on a release and props in the SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. #props channel?
  • Should we distinguish clearly between one-time contributors and active team members?
  • Should recognition appear more frequently, e.g. monthly or even at every weekly meeting?
  • Should we publish recognitions in the Make/Docs weekly updates or Week in Docs posts — similar to other teams?

Several agreed that contributor recognition should happen more often. A one-time contributor should get the contributor badge as small contributions still matter.

Defining growth paths — beyond “show up and help”

We want to answer two different needs:

  1. I want to contribute once / occasionally — how do I-do that and get recognized confidently?
  2. I want to grow into a team member or specialist — what path can I follow? What are the levels?

We could create progressive roles — for example, team members take on responsibilities like:

  • Maintaining a documentation project or focus on the handbook
  • Being the person responsible for HelpHub or DevHub areas
  • Assisting with leadership tasks (triage, reviews, release prep)
  • Being considered for Team RepTeam Rep A Team Rep is a person who represents the Make WordPress team to the rest of the project, make sure issues are raised and addressed as needed, and coordinates cross-team efforts. based on initiative over time

We want to do this more intentionally.

There is also interest in offering a structured program — e.g. a 6-month pathway where contributors could earn a recognized professional title, such as Technical Writer (Docs Team) — something they could confidently add to their CV or LinkedIn.

When and where should recognition happen?

We explored timing:

  • Should recognition align with release cycles?
  • Or would monthly or quarterly acknowledgment be more meaningful and visible?
  • Could recognitions be part of each weekly meeting agenda/notes?
  • Example: “Contributor Recognitions — username username”
  • Should these recognitions also be included in Make blog updates?

We also noted that the WordPress Credits page is only visible if a user manually clicks “upgrade,” not during auto-updates which means that WP release recognition is currently invisible to most users.

Are contributors feeling valued beyond public recognition?

Badges and props are great — but contributors also contribute in invisible ways:

  • Running meetings
  • Writing meeting notes
  • Triaging and reviewing GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ issues
  • Reviewing and updating articles
  • Leading Contributor DayContributor Day Contributor Days are standalone days, frequently held before or after WordCamps but they can also happen at any time. They are events where people get together to work on various areas of https://make.wordpress.org/ There are many teams that people can participate in, each with a different focus. https://2017.us.wordcamp.org/contributor-day/ https://make.wordpress.org/support/handbook/getting-started/getting-started-at-a-contributor-day/. tables

We asked: Are these roles recognized equally? Should they be?

And finally — does attending a Contributor Day actually advance someone’s contributor journey?
Answer: Yes — participation at a Docs table currently qualifies contributors to receive the Docs Contributor Badge, provided table leads submit their names.

What’s next?

This is the beginning of a larger effort — our goal is to build a clear, transparent contribution pathway that supports:

  • Casual contributors
  • Returning contributors
  • Aspiring team members
  • Professionals seeking career credibility
  • Future leaders

We want contributors to feel not just recognized — but valued, supported, and growing.

This conversation will continue, and we invite the wider Docs community to help co-create the next iteration of what meaningful contribution looks like.

With these points in mind, we have one clear action item which is to create a method, perhaps using gamification, to quantify the number of contributions. @milana_cap will review what options are available.

Props to @milana_cap for reviewing this post.

#contributor-recognition, #handbooks, #new-ideas

Javier Casares 4:07 pm on May 15, 2023
Tags: , handbooks   

Proposal: Handbook for Local Teams

tl;dr – Local teams, such as [es.wordpress.org] will be able to have their Handbook for a complementary use of the global Handbooks, but adapted to the particularities of the local culture instead of relying solely on a translation of the English version.

Currently, we could group the Handbooks into three types:

All these documents are in English and are maintained globally by some members of the WordPress Community.

But, in some cases, especially the local teams of each country, region or locale, there are specific documentation needs that cannot be added to the global Handbook. The clearest example is a contextual documentation of translations (the differences between English and Spanish, or between Spanish from Spain and Spanish from Mexico), or onboarding documentation for a Local Community (for example, access to their Slack).

To this, we can also add documentation from other teams that affect local elements, such as events, being able to share presentations or WordCampWordCamp WordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. information from a territory.

Three years ago, a pilot project was started in the WordPress edition of Spain for the installation of the same Handbook pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party that is used in Make/WordPress teams.

This technology is available on several sites, but with very different results. One of the biggest problems is who has access to the site and who can propose improvements or make changes, with blocking or access limitations.

That is why the following proposal is raised, based on how is already working on the Make/Hosting.

The Hosting team has a Handbook that for more than 2 years has been managed entirely from GitHub. This allows its management within WordPress to be limited to the Team Reps of the team, who perform operational tasks (ordering and reviewing content.) Because the management user is WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/, the attribution of the contents is not made to any contributor.

How is content attributed to contributors? Through GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/, since anyone who collaborates in the repository will have a versioning of the changes, and their attribution in the Activity Tab of their Profile, thanks to the synchronization between WordPress Profile and GitHub. Contribution to WordPress Documentation can be gamified.

And, an advantage and disadvantage at the same time, is how it is documented on GitHub: with the Markdown markup language. This language is a de facto standard used in many projects and allows the creation of textual content in a simple way from the keyboard (and easily convertible to HTMLHTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites.). It is also the native text language of GitHub, which allows editing directly from the platform itself, without the need to install an external program. And although it is simple to learn, it has the disadvantage that you have to learn the basic syntax, and that you have to know how to use GitHub, although it has already been proposed that this is the tool for massive use of the WordPress Community.

From here, through a simple configuration, considering that the BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. Editor can interpret Markdown natively and that there is a tool (already tested in the Hosting team) that synchronizes every 15 minutes any approved change in the Handbook repository with the WordPress site, being able to anyone in the world contribute to a team with a standard tool, whether you have a WordPress account.

As a starting point, the WordPress Community Spanish Team has been working for some time on a Handbook in which team folders and other useful folders for the Community have been created (such a general GitHub manual), and to which anyone can contribute.

This repository must be under the WordPress organization of GitHub, and apply the synchronization tool between that repository and the Handbook plugin, already installed on the [es.wordpress.org] site.

From there, anyone who wants it can contribute to the Handbook with new content, new ideas or suggestions through the automated system.

This should extend to the current Locale Managers of a management team of the edition of the locale sites, called Local Team Reps, and following the same philosophy of the Global Team Reps, being the Documentation Local Team Reps responsible for the approval and management of the publication.

Nowadays, the project for the WordPress Community in Spain is very advanced, and it would be immediate to be able to launch the pilot program of automation of local Handbooks, started 3 years ago.

Proposal by @javiercasares. Reviewed by @amieiro, @anagavilan, @estelaris, @glycymeris, @milana_cap, @mrfoxtalbot.

+make.wordpress.org/meta/

+make.wordpress.org/polyglots/

Pinging all Local Teams with Handbooks available, and Spain.

+es.wordpress.org/team/

+af.wordpress.org/team/

+ar.wordpress.org/team/

+de.wordpress.org/team/

+en-ca.wordpress.org/team/

+es-mx.wordpress.org/team/

+fr.wordpress.org/team/

+id.wordpress.org/team/

+it.wordpress.org/team/

+ja.wordpress.org/team/

+pt-ao.wordpress.org/team/

+br.wordpress.org/team/

+ro.wordpress.org/team/

+sr.wordpress.org/team/

+yor.wordpress.org/team/

+tw.wordpress.org/team/

#handbook, #handbooks

Drew Jaynes 4:02 pm on July 14, 2016
Tags: , , handbooks,   

Docs Chat Agenda – July 14, 2016

Here’s the agenda for the Docs team weekly chat, which are held Thursdays at 17:00 UTC in the #docs channel on SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/..

Current Projects Updates:

  1. Theme Developer Handbook – @kenshino
  2. Codex MigrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. (DevHub) – @drewapicture
  3. DevHub – @drewapicture
  4. HelpHub – @kenshino
  5. Inline Docs – @drewapicture

Other Stuff:

  1. Internationalizing documentation
  2. Version articles (HelpHub)
  3. Hosted about pages
  4. Open Floor

#chat, #codex-migration, #handbooks, #helphub

Kim Parsell 9:22 pm on December 11, 2014
Tags: 4.1, , handbooks   

4.1 Docs Updates

There are a number of updates that need to be made for 4.1 to both the handbooks and the Codex.

Handbooks:

There are several posts on Make/CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. about changes in 4.1 that affect the developer handbooks:

Themes: New Template Tags in 4.1

Queries Improvements:

Shared Terms: An Update on Shared Term Splitting

CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. Improvements: JS/Underscore-template-rendered Custom Customizer Controls in WordPress 4.1

I still need to add a list of Codex pages here that will need to be updated with the content from these posts.

Codex Updates:

The following are the pages that need updated or created in the Codex.

If you would like to help, please leave a comment indicating which page you would like to work on.

New default theme:

  • Twenty Fifteen page. We can use some of this content. Note: The custom color screenshots are slightly different from the .org version. Takashi Irie provided some screenshots that reflect the default colors available: https://cloudup.com/cNHOeJVOq-k (@kpdesign)

New features:

  • New Distraction-Free Writing and inline image editing toolbar in Post editor – https://codex.wordpress.org/Posts_Add_New_Screen and https://codex.wordpress.org/Pages_Add_New_Screen
  • New sessions logout button on Profile page – https://codex.wordpress.org/Users_Your_Profile_Screen
  • New Recommendations tab on Plugin Install page – https://codex.wordpress.org/Plugins_Add_New_Screen
  • New translation installation setting on General Settings and Network Settings pages – https://codex.wordpress.org/Settings_General_Screen and https://codex.wordpress.org/Network_Admin_Settings_Screen
  • Appearance menu – HeaderHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. and Background menu items now link directly to the Customizer.

#4-1, #codex, #handbooks

Samuel Sidler 11:13 pm on November 18, 2014
Tags: handbooks   

Handbooks Update: November 18, 2014

Present today were: @aj_mallory, @blobaugh, @grappleulrich, @naomicbush, @samuelsidler, @sewmyheadon, and @topher1kenobe.

Most importantly, the chat is moving to Thursdays at the same time. The next chat will be Thursday, December 4, 2014 at 21:00 UTC. We will not have a chat next week due to Thanksgiving in the US. Of course, we all idle in #docs in SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. if there are questions outside of our weekly chat.

PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party developer handbook:

  • Launched version 1 at WCSF
  • Not much traction since
  • Focus going forward is getting minor issues (on the spreadsheet) taken care of, then onto reviewing the top Codex pages and bringing over any good information so we can redirect them.

Theme developer handbook:

  • Completely migrated since prior to WCSF.
  • Minor movement just after WCSF but mostly stagnant.
  • We need volunteers to own pages so we can get moving.

If you want to help with either handbook, pingPing The act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” any of us in #docs on Slack (especially @blobaugh, @sam, @sewmyheadon, and @topher1kenobe).

Coming up on December 6 is the Docs Sprint in Seattle and in #docs on Slack.

#handbooks

Ben Lobaugh (blobaugh) 12:09 am on October 29, 2014
Tags: handbooks,   

WCSF 2014 Docs Contrib Day Notes

Purpose to see how we are doing on Docs and look towards the future

PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party handbook

  • Almost complete. One page left to write
  • Siobhan is holding back launch with the intro 😉
  • Landing page on developer.wordpress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ will be updated to unveil the plugin hb tomorrow!
  • How can we get feedback from the users on handbook pages?
  • Add list of pages from the codex that can be redirected or need content migrated into the spreadsheet

Theme handbook

  • At 67% completion
  • Future focus can be put completely on theme hb instead of splitting with plugins

Contributor days

  • Difficult to retain contributors
  • Takes a while to get them up to speed on how to contribute
  • Are still useful as contributors that do return contribute significantly

Developer.wordpress.org

  • Landing page will show the new theme
  • Theme hb link should be whited out and say coming soon
  • Need examples contributed to the code reference
  • Need a way to group together items in the functions reference. Possibly a tag that can be added. Scott (coffee2code) is looking into options
  • The JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. docs need to be pulled in. Currently exist as markdown on GithubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/
  • Need a banner on the handbooks that lets users know all content is volunteer contributed and they can get involved

Future

  • Go through codex and find pages that can be relevant to the plugin handbook
  • Siobhan will provide list of high traffic codex pages that need to be checked for content and redirected to plugin handbook
  • Need list of content that is duplicated between both plugin and theme handbook (E.G javascriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/.)
  • Where should content live that does not exactly live in either handbook? (E.G list of javascript libraries built into WordPress)
  • Need a SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. bot that will send messages to #docs when user wants to ask a question???
  • How do we easily let in new users to edit handbooks? This needs more discussion. Prefer to contact a human to get access. Preferably one of the editors
  • Will be implementing an issue tracking system that will contain tickets for things that need updated/added

Make.wordpress.org/docs

  • Instead of weekly meetings we should use the blog to post questions, get feedback, etc
  • Switch to monthly all docs team chats

#handbooks, #wcsf2014

Samuel Sidler 3:08 pm on September 30, 2014
Tags: , handbooks   

Devhub Todo List for pre-WCSF

Prior to WCSF we need a few changes on devhub so that y’all can make awesome handbook improvements as your project. I’ve come up with a list of things that seem important prior to WCSF. This list may not be exhaustive, so we’ll add to it as we come up with other things. In general, the following are in list by importance.

  • Fix image uploads on devhub, which is currently preventing us from migrating the theme developer handbook.
  • Add the Mediawiki pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party for external redirects so we can redirect Codex pages to devhub (#meta446)
  • Add voting to examples (#meta551)
  • Create a new user role for handbook editors (#meta621)
  • Add the code TinyMCE plugin to devhub
  • Various handbook design changes (#meta631)
  • Improve the design of the callout shortcodes (#meta630)

#devhub, #handbooks

Samuel Sidler 11:54 pm on September 23, 2014
Tags: handbooks   

Handbooks Update: September 23, 2014

Present today were @blobaugh, @sewmyheadon, and @topher1kenobe, with a few devhub peeps following along as we overlapped slightly. Logs are here.

  • PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party handbook: Topher worked on section 8 (metadata) and section 9 (CPTs and taxonomies) and both are now at 100%. Ben will be out of town for the next two chats.
  • Theme handbook: No updates this week. Hopefully some more next week.
  • MigrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. update: A bunch of the plugin handbook has been migrated with more being migrated this week.

If you want to get involved in either handbook, please email any of us.

Again, we meet on Tuesdays at 20:00 UTC. Hope to see more people there!

#handbooks

Ben Lobaugh (blobaugh) 6:53 pm on September 4, 2014
Tags: handbooks, , ,   

This weekend @sewmyheadon is hosting a Documentation Sprint…

This weekend @sewmyheadon is hosting a Documentation Sprint in Seattle. If you are in the area and would like to join in person join us at Uptown Espresso on Westlake. If you are remote please join us in #wordpress-sfd on Freenode.

For full details see the Meetup post at http://www.meetup.com/SeattleWordPressMeetup/events/196326602/

#handbooks, #plugin, #sprint, #theme

Ben Lobaugh (blobaugh) 6:46 pm on September 4, 2014
Tags: handbooks   

Weekly Handbook updates I ran the handbook chat…

Weekly Handbook updates

I ran the handbook chat for @samuelsidler yesterday while he was out. Present were @blobaugh @jerrysarcastic @topher1kenobe @sewmyheadon

The theme handbook is coming along. This weekend is another of the monthly doc sprints and @sewmyheadon is hoping to knock out a good chunk of the handbook.

A couple more sections of the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party handbook have been marked 100% or are ready for review. Thanks again to @topher1kenobe for doing much of the heavy lifting!

MigrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. to the new devhub has been going slowly but has had some progress.

In addition to the monthly doc sprint in Seattle hosted by @sewmyheadon there will also be a general contributor dayContributor Day Contributor Days are standalone days, frequently held before or after WordCamps but they can also happen at any time. They are events where people get together to work on various areas of https://make.wordpress.org/ There are many teams that people can participate in, each with a different focus. https://2017.us.wordcamp.org/contributor-day/ https://make.wordpress.org/support/handbook/getting-started/getting-started-at-a-contributor-day/. in Tacoma starting soon. Also led by @sewmyheadon. What a great guy!

The handbooks are still a work in progress and we are always happy to have more contributor, either writing content, editing, proofing, testing, or other! If you would like to help out please contact @samuelsidler @blobaugh or @sewmyheadon

#handbooks