Milana Cap 2:31 pm on September 15, 2021
Tags:   

[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 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.

TC 1:11 pm on September 14, 2021  

Agenda for Documentation Team Meeting September 14, 2021

The next meeting is scheduled with the following details:

When: Tuesday, September 14, 2021, 14:00 UTC

Where: #docs channel on Slack

Meeting Agenda:

  1. Project Updates
  2. 15 min repo triage/ If needed
  3. Open Floor

Please feel free to suggest agenda items by commenting on this post or raising it during Open Floor.

Thank you!

Femy Praseeth 6:45 pm on September 7, 2021  

Summary of Docs Team Meeting Sep 7, 2021

Housekeeping

Attendance

@TC, @femkreations, @milana_cap, @atachibana, @kenshino, @themiked, @joyously, @estelaris, @kartiks16, @kafleg, @kmhazari 

Where: #docs channel on Slack

Find the complete Transcript of the meeting on Slack.

Meeting Facilitator:  @TC

Note Taker: @femkreations

Next Meeting Facilitators: @kmhazari  and @TC

Project updates

@milana_cap – Work in progress on the 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/. post about the doc team’s new workflow that we can share with other teams.

@atachibana – From the content site, processing as many related issues as possible. 

@femkreations: Added labels to the existing issues in the repo.

Handling issues across all documentation

Discussion on adding a dedicated time for repo triage :

by @milana-cap

The easy and straightforward issues don’t need triage but for issues that need discussion and the team’s decision, we could add a label like “discussion” or “needs discussion”.

Based on the number of issues under that label we can plan the meeting time for triage.

@kenshino: The triage is required so we can build the habit and for people to pick up issues.

DECISION: Dedicate 15 mins to triage issues during the weekly doc meetings. Depending on the number of issues we can make changes to the triage time if needed. Keep this in mind when making meeting agendas.

Discussion on adding labels to issues requesting new document/article:

by @milana-cap

This is related to the PR – issue template that’s requesting a new page/article.

@milana-cap has added labels for 5.6, 5.7, 5.8, and 5.9 for releases.

@kenshino: At some point, we should have documentation tied to specific releases.

DECISION: Add “new document” label to the issues requesting new document/article, for now. @femkreations to update the issue template with the label.

TC 3:57 am on September 7, 2021  

Agenda for Documentation Team Meeting September 7, 2021

The next meeting is scheduled with the following details:

When: Tuesday, September 7, 2021, 14:00 UTC

Where: #docs channel on Slack

Meeting Agenda:

  1. Project Updates
  2. Handling issues across all documentation
  3. Open Floor

Please feel free to suggest agenda items by commenting on this post or raising it during Open Floor.

Thank you!

 

Michael Burridge 3:59 pm on September 1, 2021  

Summary of Docs Team Meeting Aug 31, 2021

Housekeeping

Attendance: @zzap, @atachiba, @basil, @TC, @Kris Hazari, @Kartik Shukla, @femkreations, @estelaris, @themiked, @joyously, @Michael Burridge

Where: #docs channel on Slack

Find the complete Transcript of the meeting on Slack.

Meeting Facilitator:  @zzap

1. Project Updates

@atachiba:
New repository is working quite well.

2. Handling issues across all documentation

@atachiba:
@Kenshino (Jon) is still working on the readme

@zzap
New maintainers added to the repo

@femkreations:
Intends to complete 2 overdue tasks this week –
1. Creating templates for new doc request and fix bugs in existing.
2. Adding labels to existing issues in the repo.

3. Documenting processes – new workflows and ways to contribute

@zzap:
This page in particular that needs updating with new info –
https://make.wordpress.org/docs/handbook/workflows/reporting-an-issue/
There are new members (TC and @yusuf saifur-Rahman) interested in doing this in order to learn the process of contributing along the way.

@zzap:
We should start migrating end user 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 docs issues from trelloTrello Project management system using the concepts of boards and cards to organize tasks in a sane way. This is what the make.wordpress.com/marketing team uses for example: https://trello.com/b/8UGHVBu8/wp-marketing. board to githubGitHub GitHub is a website that offers online implementation of git repositories that can 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/ repo and use release labels – @Michael Burridge to look at this.

@zzap:
To co-ordinate with 5.9 release team (when announced) to make communication between release team and docs team a habit.

4. Open Floor

@joyously:
Do the new folks have the capabilities they need, to do things like add labels or whatever?
@zzap added some accounts at the github repo.

@zzap to ask 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. to connect github repo with 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/. channel so that we are notified for every new issue.

@joyously:
Was there still a planned automation of opening issues directly from the docs?
@zzap:
It is planned but first we want to see how this will go and what exactly we want the workflow to look like. I believe that would be 2nd phase.

Milana Cap 11:28 am on August 31, 2021  

Agenda for Documentation Team Meeting 31 August 2021

The next meeting is scheduled with the following details:

When: Tuesday, August 31, 2021, 14:00 UTC

Where: #docs channel on Slack.

Meeting Agenda:

  1. Project Updates
  2. Handling issues across all documentation (Ref. Ticket 5863)
  3. Documenting processes – new workflows and ways to contribute
  4. Open Floor

Please feel free to suggest agenda items by commenting on this post or by raising it during Open Floor.

Thank you!

Akira Tachibana 9:54 am on August 31, 2021  

Summary of Docs Team Meeting Aug 24, 2021

Housekeeping

Attendance

@estelaris @atachibana @themiked @kenshino @basilh @femkreations @joyously

Where: #docs channel on Slack

Find the complete Transcript of the meeting on Slack.

Meeting Facilitator:  @atachibana

Project Updates

HelpHub content team has started the new repository and it is working well.

New repository to hande issues across all documentation

@kenshino:
New official repository for documentation issues created: https://github.com/WordPress/Documentation-Issue-Tracker. New Issues have already been reported in the new repo: https://github.com/WordPress/Documentation-Issue-Tracker/issues

Management of the repo:

@kenshino who is preparing README.md:

Focusing on how one would use the repo so that
1. Issues are picked up
2. There’s no overlap / repeated work
e.g. I’ll be putting in guidelines such as
– If you are working on an issue, assign it to yourself
– If you don’t have permissions to assign, please let us know you’d like to pick this issue up and we’ll do the assignments

Issue Templates

@femkreations who is making on updates of issue template:

https://github.com/WordPress/Documentation-Issue-Tracker/pull/12

@kenshino :
we can make 2 issue templates. One for current doc fixes, one for doc requests.
Let’s start with one of the following

  • Doc Fix / New Doc
    OR
  • User Doc / Dev Doc

@joyously :
Can there be an initial input of a URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org, and that is used to choose the correct template?

@kenshino :
It’s a button. It will look like this.

@basilh :
Most of these have not used the template. Will these be discarded and required to use the new templates)?

@atachibana:
My failure. I copied opened issues from other repository. We should follow the template and I will do.

Labels

@femkreations:
Do we need to manually assign labels to the existing ones?

@kenshino:
Yes please manually assign for now

Open Floor

@kenshino :
We can probably use one of the meetings to do some triage

Femy Praseeth 8:06 pm on August 17, 2021  

Summary of Docs Team Meeting Aug 17, 2021

Housekeeping

Attendance

@atachibana @femkreations @kenshino @themiked @mkaz  @bgturner @tacitonic @basilh @kmhazari @ashiquzzaman @kartiks16  @thisisyeasin

Where: #docs channel on Slack

Find the complete Transcript of the meeting on Slack.

Meeting Facilitator:  @atachibana

Note Taker: @femkreations

Agenda: https://make.wordpress.org/docs/2021/08/17/agenda-for-documentation-team-meeting-17-august-2021/

Project Updates

No new project updates for the Style Guide and HelpHub. 

Handling issues across all documentation

@kenshino:
New official repository for documentation issues created: https://github.com/WordPress/Documentation-Issue-Tracker. New Issues have already been reported in the new repo: https://github.com/WordPress/Documentation-Issue-Tracker/issues

Management of the repo:

The doc issues already in the HelpHub/issues repo will be copied by @atachibana to the new repository. HelpHub/issues will be closed.

In the future, all new issues will be added to the new official repository. 

Anyone can open an issue and add comments. After the document updates are completed, the issue will be closed. 

The current implementation of the docs repo is considered as v1.

Contributors would need to register a GithubGitHub GitHub is a website that offers online implementation of git repositories that can 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/ account if they want to write up an issue.

How will the issues be assigned?

We can set it up such that certain Issue templates automatically assign a user or we can do this manually via a triage weekly.

How to track per project, for those that are in GitHub already (Eg: GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/)?

There are issues for documentation already in the WordPress/gutenberg repo – the intent is not to move those out but to create a place that people could go if they are unsure about where to post issues. They can be triaged and routed to the right team later.

The idea is to have a single place that anyone can post a doc issue and not have to know what project to go to. If someone knows it’s a Gutenberg doc, they could go directly there to file an issue.

Issue Templates:

Purpose of the issue template: To ensure that when a user reports an issue, all required information is provided right off the top.  This template will guide the issuer to provide structured data which will help the documentation team to easily fix the issue.

Suggested headers by @themiked

  • URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org showing issue
  • Section of Page showing issue
  • description of the issue
  • why it is a problem
  • suggested fix

@femkreations will pick the suggested headers and create a pull request to add in an Issue Template.

Labels:

Each handbook will have its own project-specific label.

Why are we not using separate projects for each handbook?

  • GitHub issues now have Projects where previously we could only use Labels.
  • GitHub “Project” is more heavy weight than a label.
  • GitHub Projects are getting an overhaul soon. So we will wait for the changes to come in and work on getting this set up, in the meantime.
  • The Project View is less a classification of an issue and more a workflow tool, like a kanban board.

@kenshino will define the default labels that we’ll use.

Update docs to point to the Tracker:

@kenshino to add all project leads to the GitHub Team and they will have “maintain” access. 

All project leads to DM their GitHub username to @kenshino.

All project leads should update their docs to point towards using this Issue Tracker.

Write a guide on how this issue tracker is used and managed:

We will take Gutenberg’s contributing guidelines as a basis and expand on it.

@mkaz to create a PR for the README.  @themiked to help edit the guide.

Akira Tachibana 9:32 am on August 17, 2021  

Agenda for Documentation Team Meeting 17 August 2021

The next meeting is scheduled with the following details:

When: Tuesday, August 17, 2021, 14:00 UTC

Where: #docs channel on Slack.

Meeting Agenda:

  1. Project Updates
  2. Handling issues across all documentation (Ref. Ticket 5863)
  3. Open Floor

Please feel free to suggest agenda items by commenting on this post or by raising it during Open Floor.

Thank you!

Femy Praseeth 7:35 pm on August 9, 2021  

Summary of Docs Team Meeting Aug 3, 2021

Housekeeping

Attendance

@milana_cap, @femkreations @chaion07,  @basilh, @tacitonic, @johnbillion, @estelaris @themiked, @jrf  @fierevere 

Where: #docs channel on Slack

Find the complete Transcript of the meeting on Slack.

Meeting Facilitator:  @milana_cap

Note Taker: @femkreations

Project Updates

@tacitonic – No updates for the Style Guide. 

@milana_cap – DevHub feedback code to be done by next week.

Please refer to the Summary for details on the tool for handling the issues with documentation such as if docs are out of date, has an error/typo, etc.  For suggestions (and questions), please leave comments on this post 

@femkreations – Working on the GB end-user docs updates based on the TrelloTrello Project management system using the concepts of boards and cards to organize tasks in a sane way. This is what the make.wordpress.com/marketing team uses for example: https://trello.com/b/8UGHVBu8/wp-marketing. board for the WordPress release 5.6. The goal is to clean up the board and move everything to the new tool we’re going to decide on.

@estelaris – Will be back next week to continue cleaning up the project.

Open Floor

Discussion 1: 

@johnbillion is looking for someone to run the WP parser (which constructs all the function, method, and hook documentation on the dev site) over trunk after 51529 (51530, 51531, and 51532) and check that the docs for the affected methods are still parsed correctly. 

Some annotations have been added in between the phpdoc 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. and the function itself, so we need to make sure that, with the extra annotation immediately above the method, the phpdoc block gets detected and parsed correctly. If it breaks, the annotations need to be moved to, before the phpdoc block. 

If anyone has documentation on setting up parser or would like to help out, please share in the #docs channel. This needs to be completed before the 5.9 release.

@jrf  added: WordPress-Docs uses only “upstream” PHPCSPHP Code Sniffer PHP Code Sniffer, a popular tool for analyzing code quality. The WordPress Coding Standards rely on PHPCS. Commenting sniffssniff A module for PHP Code Sniffer that analyzes code for a specific problem. Multiple stiffs are combined to create a PHPCS standard. The term is named because it detects code smells, similar to how a dog would "sniff" out food. at this time and she has submitted fixes for those sniffs to PHPCS and those PRs have been merged. She expects PHPCS 3.6.1, which will include the fixes, to be released before PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php. 8.1/WP 5.9, so we should be good. She still has to review if there are any sniffs within WPCSWordPress Coding Standards A collection of PHP_CodeSniffer rules (sniffs) to validate code developed for WordPress. It ensures code quality and adherence to coding conventions, especially the official standards for WordPress Core. that need adjusting and will be addressing them soon.

Discussion 2: 

@basilh raised the question: How can one track the progress of a query submitted through the feedback form at the button on a support article. 

@milana_cap added: When the issue is reported, depending on its complexity, it is either fixed right away or an issue is opened in the GitHub repo for Helphub. 

Many of them are either spam or support questions that should be asked in forums and we don’t have enough people to respond to them in a timely manner. If anyone is interested in this position, please 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.” @milana_cap.

@atachibana is in charge of general end-user docs and we’re still working on the block editor end-user docs, all of which are the WordPress articles in the HelpHub. 

@fierevere added:  She has cleaned spam, made sure that spammers are banned, deleted support questions, and fixed simple issues for HelpHub, and will report more complicated issues in the #docs channel on Slack.