The Docs team tracks, modifies, and improves documentation across the WordPress project including in: Core Core is the set of software required to run WordPress. The Core Development Team builds WordPress., the Codex, the upcoming Handbooks, and other parts of WordPress.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/ and related websites. Throughout the project, code and design issues get tracked in trac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. (both the core and meta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. tracs), but this method isn’t the most efficient for tracking documentation issues. Thus, a documentation issue tracker has been proposed by the Docs team.
Goals
The documentation issue tracker has two main goals:
- easy reporting of issues throughout the project to Docs team
- easy tracking of reported issues
A successful documentation issue tracker ultimately will improve documentation throughout the project.
Stakeholders
The docs team is the major stakeholder for this project, given they will be primarily using the tracker.
An owner is needed.
@samuelsidler will project manage and work with the docs team and owner.
Solutions
There are two major features to a documentation issue tracker:
- reporting interface
- tracking interface
To ensure we complete our goals, we’ll use the following metrics:
- user tests of end users reporting documentation issue (to ensure it’s easy)
- feedback from Docs team for tracking
Components
As stated above, there are two components to the documentation issue tracker: Reporting and Tracking.
Reporting
The reporting interface will need to collect a bit of information automatically (when possible) for submission to the tracker. Specifically, we’ll be collecting the username of the reporter, the date an issue was reported, an issue type (user selectable), link to page (using the referrer, when possible), and a custom, user-created description. Users will need to be logged into their wordpress.org account to file an issue. If they are not logged in, we’ll redirect them to the login page first. There may be interactions that break here, for example the referrer may get lost if a user has to log in before reporting an issue.
We still need to determine where this reporting interface will exist (only on a specific page or a link everywhere?)
Completed Steps:
- determined more details about the what information to collect and when
- @karmatosed designed reporting interface
- initial mockups posted for feedback
- final mockup created
- @Otto42 has agreed to develop the reporting interface
Next Steps:
- work with the Docs and Meta teams to determine where the interface will live
Tracking
The tracking interface will be used mostly by the Docs team to track incoming and active issues. Part of this interface involves viewing issues individually and changing their status. Editors (or Gardeners) will need specific permissions to make actions. More specifically, we will require users to have the “Editor” user role to resolve issues.
On the tracking interface, we’ll want to display the following information: username of the reporter, the date an issue was reported, issue type, link to page, person assigned to an issue, a button that assigns an issue to you, and a resolve check box. A user-created description will exist and can be revealed with a “reveal arrow.”
Completed Steps:
- made decisions about specific information required and user roles that will be able to resolve issues
- @karmatosed designed tracking interface
- initial mockups posted for feedback
- final mockup created
- @Otto42 has agreed to develop tracking interface (possibly using P2 P2 or O2 is the term people use to refer to the Make WordPress blog. It can be found at https://make.wordpress.org with the resolved posts plugin 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.)
Next Steps:
- determine where tracker will live
Note: As it stands right now, this issue tracker will likely have a one-size-fits all tracking interface and not allow much customization as far as tracking. However, eventually we will want to allow sorting by “component.”
#docs-issue-tracker, #projects, #spec
