[Announcement] New workflow for reporting documentation issues

For a few weeks now Documentation team is testing out new workflow for reporting issues – a GitHub repository which will be a single, centralised place for reporting all documentation issues. How and why we decided to do this can be found in team’s meeting notes.

What we hope to achieve with this workflow:

  • Easier contribution in form of reporting issues – even though this workflow still requires another account from contributor (the 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/ one), with this workflow contributor doesn’t need to know which part of documentation is issue for. They can just report the issue and move on, if they so wish. We lost many one-time contributions due to the complicated workflow for reporting issues.
  • Easier contribution in form of fixing issues – with all projects and their different reporting issues tools, contributor who wanted to join team and work on fixing issues had to decide which project they wanted to work on before even seeing issues. With everything in one place they can browse all the issues, find the ones that seem interesting and then look for advice on fixing it.
  • Some projects didn’t have any way for reporting issues except for coming to #docs 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/. channel and hoping that someone will see it. This way is deprived of a place where the issue would be discussed as many things get lost in Slack noise. Also, this way is almost impossible to keep track of contributors and give them credits for their contributions.
  • Easier managing of projects and documentation in whole – team members have better overview of everything that’s happening in every Docs project, can help out in projects they usually don’t work on and have a general picture of WordPress documentation as a whole.
  • Easier contributions tracking – with every issue, comment, contribution being saved in one place, we have a better understanding of how certain parts of docs were created and who worked on them.
  • Better planning and setting goals with GitHub projects.
  • Better understating and following progress and statistics for each project by structured labeling system.
GitHub issue discussion.
GitHub issue discussion

We are still configuring labels, templates and the repo itself; and still figuring out the best way to work on/with issues. For the future we hope to connect this repository with the actual documentation at 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/ so that contributions can be make directly on the page with the issue which would automatically create new issue and apply proper labels.

In the next phase, which will be soon, we will start using GitHub Projects for managing all the issues.

GitHub Project board for managing all GitHub issues from the repository.
GitHub Projects board

Documentation Team is managing all documentation as an unified project and is adopting appropriate tools in order to do so.

As always, if you have any questions or suggestions, please leave the in comments bellow.