This discussion started in Slack during one of Docs team meetings. It was discussion about the best tool for tracking progress and issues for 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 documentation. However, the question of tool is widely applicable to all Docs projects, hence the need for this post and discussion.
Having complete documentation on Codex made contributing to Docs team easy in a way that everyone, as long as logged in, could modify existing or add completely new parts of it. However, this method had its flaws. It was impossible to track which parts of documentation were modified. And if we can’t track modifications then we can’t check the correctness of newly added information as well as the quality of code examples.
It took few years but we moved big parts of Codex to new places, built on WordPress. While we have more control as complete content goes under our review, this move made contributions to documentation team fairly difficult. The process itself is unclear, different Docs team’s projects use different tools (none of which covers all we need) but the common scenario we end up with is people reporting issues in 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/. #docs channel.
The Tools
Documentation team uses several tools in contributing process. We have several Trello boards with more or less activity. Also, progress for almost all projects is tracked in Google Docs.
HelpHub content is tracked in Google Drive while development uses GitHub repository for development and Meta Trac for production issues.
Contributing to code reference can be done with code examples through User Contributed Notes (e.g. User Contributed Notes for activate_plugin() function) or with inline documentation via Core Trac (which is more Core Core is the set of software required to run WordPress. The Core Development Team builds WordPress. than Docs team’s responsibility).
Plugin developer handbook gets updated when someone reports issue in Slack channel while Theme developer handbook used to use Trello board but we handed over leadership to Theme Review Team (even though Docs team is still helping when needed).
Common APIs handbook uses Google Spreadsheet.
Block editor uses Trello board and Google docs for end user documentation and GitHub for developer’s documentation.
We also have Documentation Trac available. It hasn’t been used for anything before.
What is the problem?
Different projects have different workflows and, therefore, different tools. However, we have several problems to solve:
- Access – while we do welcome everyone to contribute to Docs team, we also need to be careful with giving access to handbooks hosted at wp.org. If we want to make sure that only curated info gets into handbooks we need to limit access. That also means that whole burden of reviewing and maintaining handbooks falls on these few people who have access.
- Keeping track of contributions and contributors – the easiest way to keep track of contributions/contributors is to use tools we have available at wp.org (Trac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. and Slack). On the other hand, Trac is not the most intuitive tool for wider range of WordPress users and Slack tends to burry information so the history is lost in tons of archives. Also, in some cases it is important that we have a history of a decision/discussion available at one, easy to access, place.
- Project managing – each project is different but it is a project nevertheless. It is important that the tool we use for it have project managing features which will make contributing to the project easier (joyful is preferable).
- Onboarding and taking over – Onboarding is huge problem of every open 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. project and it’s naive to think we can solve it with one tool. But also, it’s not just to tool we need to onboard people in, it’s the workflow as well. The tool we chose and the way we use it should be intuitive enough not to stand on our way to contribute and not to make project depended on a specific person. Most of this could be solved with a detailed documentation on the workflow itself.
- There could be more, leave your thoughts in comments.
What are we deciding here?
We are not trying to decide on one tool over the other. We are trying to discuss all the tools we already use, how they solve our problems and how they help our workflow.
Most importantly, we want to figure out the way for reporting and discussing Docs issues. Preferably, we would come up with a unique way for all docs projects but given the differences between projects, it wouldn’t be considered as a failure if we don’t.
However, it is important that we come up with a way to report and discuss issues for each project. Results of this discussion will end up in our Handbook as a reference for contributing to Documentation team.
Please, leave your thoughts in comments.
