WordPress documentation is about to improve by leaps and bounds. At the moment, trying to get involved contributing to documentation can be quite confusing. Unless you know the current docs inside and out, it’s not easy to find gaps or missing pieces that need attention. That’s where an issues tracker comes into play.
What is a documentation issues tracker?
A docs issues tracker is to documentation what trac is to code. The issues tracker provides a central place where users and contributors can report and track progress on issues specific to documentation.
The Drupal project has a nice example if you want to see one in action.
The idea originated with the WordPress Docs Team. When Siobhan McKeown outlined the idea for the tracker, she cited two important problems that the issues tracker will solve:
- People want to contribute to docs but don’t have a central list of tasks that they can sit down and tackle
- More and more contributor days are happening and our issue tracker will be a place where organizers can find tasks for the day
Example issues one might report include documentation that’s out of date, incomplete docs, pages that need editing, missing sections, a dead link, code examples that are broken or need updating.
Tammie Lister designed a mockup of the tracker planned for WordPress:
As you can see, it’s simpler than trac in many ways and designed to be easy for anyone to quickly create a report on an issue.
The Docs Tracker is Now in Development
To get an understanding of the system that contributors have been using so far, I asked him how documentation issues are currently being resolved. It seems that right now, there is no central place for everyone to jump in and work together. He replied:
Currently, documentation issues are resolved and tracked manually by individual contributors. There isn’t an easy way to report issues or request new documentation. The documentation issue tracker will allow two things: 1) anyone can report an issue with documentation and 2) the docs team can track all open issues to have a better picture of the state of documentation across the project.
Sidler believes that the new issues tracker will help open up contribution to WordPress docs in a major way. “The tracker is focused on making things easier for the docs team first and foremost. But any community member will be able to report issues to it, opening the door to participation,” he said. Besides the Docs Team, he anticipates that the Support Team will also be likely to use the tracker for the documentation they manage.
The designs have been finalized and Sidler reports that Otto has happily agreed to develop the new tracker. How soon will we see it in use on WordPress.org? Sidler says, “It’s hard to say exactly how long an issue tracker will take to build, especially with the upcoming holidays, but we’re closer than we’ve ever been.” The plan is to roll it out in beta first and Sidler will be organizing users for testing. “We’ll put links on a few docs to test the reporting interface with end users before rolling it out to all documentation.”
A documentation issues tracker is a must-have tool for any large open source project. Sidler is hoping that it will streamline issue management.
Ideally, more issues will get reported and then fixed with an issue tracker in place. Having an easy way for anyone to report an issue should increase the number of reported issues. Likewise, having a central place to track issues will make them easier to fix.
I’m excited to see the documentation issues tracker implemented on WordPress.org. It has the potential to exponentially increase the contribution to docs as well as collaboration among Docs Team members. If you’re eager to contribute to WordPress docs but don’t know where to get started, the tracker will help you to find a place to jump in. We’ll let you know when it’s live on WordPress.org.
This is awesome news and absolutely will rocket the amount of participation and contribution — to make Documentation/ Codex a better place for all!
Thanks all involved for doing this extra work, we’ll all benefit from it.