Housekeeping
Attendance
@chaion07, @atachibana, @ashiquzzaman, @kenshino, @mburridge, @tacitonic, @themiked, @femkreations, @courane01, @thisisyeasin, @joyously, @milana_cap
Where: #docs channel on Slack
Find the complete Transcript of the meeting on Slack.
Meeting Facilitator: @kenshino
Note Taker: @milana_cap
Next Meeting Facilitator: @milana_cap
Project Updates
@tacitonic – No substantial updates for the Style Guide. Currently writing the last remaining article on A for the Word List. After this one we could finally announce/publish a post WordPress-wide.
@milana_cap – DevHub and HelpHub have been updated with 5.8 changes. Block 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 end user docs is missing changes from previous releases (this should be a priority) and block editor developer docs is a bit ahead of WordPress release.
Handling issues across all documentation
The Problem: Docs team has more than few different projects to maintain. All these projects have different ways of maintaining which caused different ways for reporting issues. With the team being understaffed most of documentation on contributing is out of date, which makes contributing really difficult. Even for just reporting an issue. There is no system, issues get reported everywhere but mostly in our Slack 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 if we don’t act on it right away it gets lost. Sorting and triaging issues doesn’t exist.
The Solution: This might not be the best solution for the long run but the team wants to at least start addressing the problem by defining one centralised place where all of the docs issues will be reported. This will ensure unique experience for contributors who report issues, but also for contributors who want to work on those issues – they would have a single place to filter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. through all the issues and choose which ones to work on.
The team needs to decide which tool will be in use by defining features this tool needs to be useful. GitHub 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/ repo and Docs Trac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. were mentioned the most. Docs Trac has benefits of contributors being already logged in which is easier for tracking contributions (and perhaps automating profile badges). GitHub, in it’s default setting, demands another account from contributor (even though this can be worked around with many automation tools at our disposal (GitHub + ZenHub and the upcoming GitHub Projects upgrade). This tool would also be in use for tracking release changes and updates to all docs, where appropriate.
Focus here is on reporting, commenting and updating issues.
The features team identified:
- Templates how to report issue so people can create issues with guidance.
- Useful labeling system – If we have labels “diagrams needed”, “screenshots needed”, people who don’t like to write can still contribute.
- Owning the system and not waiting for months to get something updated.
- Filtering is important too.
- Make it really easy for new contributors, because making it easy to get involved will help folks continue to be involved.
- We want to be able to just say – VISIT our issue tracker and pick anything that says “good first issue”.
- From the perspective of someone reporting the issue, the flow: click on button – > explain the problem – > click on submit would be ideal – Gitbook docs has something like this.
- If you’re a project lead – you can set it such that you’re notified on specific labels.
- Have issues organized with a way to easily find what should be revised, do the work, save the revision for approval.
- Automation could be something like triage@wp.org that has it’s own github account, and that is used to put publicly reported ideas into this system, into a triage bucket. So contributor reports an issue, they do so using the form. The form itself, is a front end for some magic that turns that submission into a github issue, under a generic triage account. The email address was only for the account creation and it removes the requirement for a user to create yet another account somewhere.
- If anyone completes an issue – they should PR into the contributor list to add their own WordPress.org nickname in there and that’s how we could track contributions in the future – that sounds like the kind of thing that should be automated.
- Maybe we can use it to block WP releases until the docs for that release are complete #daretodream
Things we could track, besides issues:
- a user notices a simple typo
- translation status of specific pages/content
- special project progress
- editing status of specific pages in a handbook (using tags for example)
- etc
It’s worth noting that the Audit tool (proposed by Training team) could have some of the features that will be very helpful for Docs and some other teams. The audit tool could give something like following workflow:
- you’re on page (regardless where, it shouldn’t matter) and see out of date/wrong/missing info
- you highlight the wrong part
- you click on “report/edit” on the page
- textarea popup to add description if needed
- you submit
If you have any suggestions or questions, do leave your comments below. The tool is not yet selected and we’ll try to do that on the next meeting.
