Documentation Issue Tracker Specification

The Docs team tracks, modifies, and improves documentation across the WordPress project including in: CoreCore 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.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/ and related websites. Throughout the project, code and design issues get tracked in tracTrac 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 metaMeta 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:

  1. reporting interface
  2. 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 P2P2 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 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)

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

developer.WordPress.org Specification

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/ is a new portal for WordPress developers. It will provide educational tools to teach people about WordPress development (in the form of handbooks) and a reference for the WordPress codebase (the code reference).

Goals

developer.WordPress.org has several goals:

  • improve current resources for developers
  • encourage best practices in WordPress development
  • educate new developers

If the site succeeds at encouraging best practices in WordPress development, a potential side-effect is an improvement in users’ experience of third party plugins and themes.

Stakeholders

The primary team identified as a stakeholder is the docs team. However, three other teams are associated stakeholders and their input will be used in the development of the resources. They are: coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., themes, and plugins. The net result of a successful implementation means improved documentation and educational information for new, intermediate, and experienced developers, ultimately affecting the entire project.

@siobhan has volunteered to own this project.

@samuelsidler will project manage and work with the above stakeholders (e.g., communicate with the team reps from each team).

Solutions

We’ve identified two features of the developer portal that will complete the goals of this project:

  1. developer handbooks
  2. code reference

To ensure we complete our goals, we’ll use the following metrics:

  • stats from the both the code reference and handbooks to ensure they’re being used
  • feedback from the development community by way of surveys, comments, and weekly meetings
  • full testing of handbooks by amateur developers; they should be able to work through the handbooks and achieve the individual handbook’s goal by the end.

Components

developer.WordPress.org can be broken up into three components, each with their own specific tasks.

Design

Designs need to be created for:

  • main landing page
  • handbook landing pages
  • individual handbook pages

Completed Steps:

Next Steps:

Handbooks

Two handbooks are currently in progress and are pivotal to the success of this project. Both are being spearheaded by @hanni.

Other handbooks have been proposed, but are not required to complete this project:

  • Introduction to WordPress Development
  • Server Configuration for WordPress
  • Building Networks with WordPress MultisiteMultisite Multisite is a WordPress feature which allows users to create a network of sites on a single WordPress installation. Available since WordPress version 3.0, Multisite is a continuation of WPMU or WordPress Multiuser project. WordPress MultiUser project was discontinued and its features were included into WordPress core.https://codex.wordpress.org/Create_A_Network.

developer.WordPress.org should launch with the theme and 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 handbooks complete. More contributors are needed in this area to assist with writing, developing, editing, and testing the handbooks.

Next Steps:

  • review current handbook content
  • push handbooks to developer.wordpress.org with basic design (as seen on core contributor handbook); starting with theme dev handbook which is furthest along
  • @hanni to draw up further plans

Code Reference

Development of the code reference is currently in progress.

Completed Steps:

Next Steps:

The inline docs are going to be updated by the core team in 3.7 to ensure that we get a good output. Once the alpha is up and running we’ll need a team around making improvements to it. This will include:

  • ongoing development of the parser
  • extending the functionality (we’ll use meta.tracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. for features, enhancements, bugs, so people can upload patches)
  • testing the workflow to make sure that people can contribute explanations and examples
  • moving relevant information from the Codex
  • having a drive to get people to add information
  • ongoing curation and moderation

#devhub, #projects, #spec

Updated Project Queue

I just posted an updated Project Queue page, which is linked to in the nav bar of all the make/metaMeta 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. pages. The page includes just about all known projects the meta team is working on (based on the digestible list I posted before). There’s a few other projects that we’ll be adding to the list soon.

The Project Queue also includes an overview of how projects will work on 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/. Note that in most cases, the project manager will be me, but it may vary.

To start tackling this list, I’ve been working with @siobhan and will be posting a developer.WordPress.org spec later this week for feedback.

If you have questions about the process listed or if you think a project is missing from the list, let me know here.

#projects

Digestible WordPress.org Project List

Hello! My name is Sam and I work for Audrey organizing and scoping projects. I’ve spent the last three weeks talking to a lot of people and trying to get a better sense of all sorts of projects that exist throughout the WordPress community, especially on 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/ and all of its associated websites.

There’s a lot of pieces to wordpress.org and everything can be better. I’ve identified a number of areas that have been mentioned over and over and that need a lot of focus. Based on my conversations, I’ve taken a first stab at prioritizing everything below.

I want to emphasize that none of the ideas I put after the projects have been decided; I just wanted to give some general thoughts I had about what each project means. Everything below is at varying degrees of progress. Some things are nearing completion! Others are just ideas, with no scope at all. And there are only so many things that can be worked on a time, so a lot of these projects might get put on the back burner as we focus. As we decide to move forward on a project, we’ll want to decide what the goal is and then scope out exactly what needs to be done.

Because I’m pretty new to the WordPress community, I’m sure I’m missing some things. Feel free to comment and let me know. Nothing is too big or too small.

To start, these are a few ongoing projects, by which I mean these are things we should take into consideration as we work on any part of wordpress.org.

  • Open SourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL.: Many parts of wordpress.org are closed to participation. We should open source websites as we work on them. (In progress.)
  • Stats: Integrate stat collection throughout each part of the site so we know what features are most used.
  • General Design Improvements: Every part of wordpress.org should have a consistent design. We should also investigate implementing a responsive design across all sites, though this is likely targeted for the medium term or later.

And here’s the entire list of projects, in order by the priority I determined:

Immediate Priority

  • Increase WordPress and WordPress.org Participation: Let’s make it dirt simple to contribute to the WordPress community. For starters, we can do a better job answering the “Where do I go?” question. But we can also do a better job at recognizing contributors from all over the project and keep attrition low.
  • Improve make.wordpress.org: Redesign the front page of make.wordpress.org to be useful. It should be the home page of WordPress contributors. Ideally, make.wordpress.org will show an overall view of what’s going on throughout the project and incorporate information about each team.

Short Term

  • Support & Documentation Hubs: Two separate hubs, but closely related in many ways. Our story for end-user support isn’t great and should be improved. Likewise, the documentation in the Codex can be overwhelming for new developers. (Below are some sub-projects.)
    • Handbooks: Well-written online resources that give a good overview of how to get involved (contributor handbooks), how to develop for WordPress (developer handbooks), or how to use WordPress (support handbooks).
    • Developer Resources Hub: We need to point developers to the part of the project they are most interested in and link to relevant handbooks and resources. A code reference is an easy win for documentation and would replace a lot of Codex pages with solid, up-to-date information.
    • Support Hub: As WordPress gets into the hands of more users, we need a better end-user story. Many relevant documents exist on wordpress.comWordPress.com An online implementation of WordPress code that lets you immediately access a new WordPress environment to publish your content. WordPress.com is a private company owned by Automattic that hosts the largest multisite in the world. This is arguably the best place to start blogging if you have never touched WordPress before. https://wordpress.com/, but would need to be tailored to the wordpress.org audience (i.e., someone running their own installation of WP but maybe not understanding what that means).
  • Profile Improvements: At present, it’s hard to know what individual community members are working on. We should vastly improve profiles, showing activity from across wordpress.org (including, but not limited to: tracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/., SVNSVN Apache Subversion (often abbreviated SVN, after its command name svn) is a software versioning and revision control system. Software developers use Subversion to maintain current and historical versions of files such as source code, web pages, and documentation. Its goal is to be a mostly compatible successor to the widely used Concurrent Versions System (CVS). WordPress core and the wordpress.org released code are all centrally managed through SVN. https://subversion.apache.org/., forums, theme and 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 directories, localization work, event participation, etc). Using this data, we can better recognize contributions. Profiles should be the place to go to see what someone has been working on. Likely, these improvements will take place over time, as we work on individual areas of the site. (Partly in progress via Google Summer of Code project.)

Medium Term

  • Themes Directory Redesign (feature themes better)
  • Improvements for the i18n Community
    • Create “global.wordpress.org” (i18n community portal)
    • Improve locale sites (Rosetta)
    • Improve translator tools and resources (Translate)
    • Improve international forums
  • Improve WordPress.org Home Page
  • Support ForumSupport Forum WordPress Support Forums is a place to go for help and conversations around using WordPress. Also the place to go to report issues that are caused by errors with the WordPress code and implementations. https://en.forums.wordpress.com/. Improvements

Long Term (or Low Priority)

  • Plugin/Themes Directory
    • Improve Tools and Collaboration (better support forum tools, better code collaboration, better bug tracking tools)
    • Improved Plugin Rankings
  • Workshops (i.e. learn.wordpress.org)
  • jobs.wordpress.net (Some work being done now; more work in the future)
  • “Ideas” Improvements
  • Mailing List Page Redesign

Let me know what you think!

#projects