Introduce maintainers to frontend docs
Problem to solve
The quality of technical docs and frontend docs in particular is lower compared to a typical handbook page. More specifically:
- Related information is spread across different page roots, making it hard to form a holistic view of our practices and breaking the
single source of truth principle. For example, pages related to frontend testing are located in Styleguide, Vue, and Frontend-testing - The content of the documentation page sometimes is not 100% clear, concise, or easy to navigate.
- Some of the information might be missing which might lead to confusion (for example)
Further details
This problem is more visible for new starters as they are the ones relying on the docs the most. However, we must have an explicit single source of truth for our conventions and best practices. That would help not only the new starters but also the more experienced team members who might not be up to date with the most recent changes (for example)
Proposal
To improve this I propose to assign Maintainer(s) for each area of Frontend Docs. They would make sure the docs in the area are concise, up-to-date and properly structured. These people could also be automatically assigned to MRs to respective sections of the docs to make sure new additions are in line with the overall structure of the docs and are of high quality. This would allow us to keep everyone can contribute principle, while also increasing transparency and making it easier for people to find reviewers for their MRs to the documentation.
It could be useful to add this person to code owners for that particular page as well, but I would love to hear feedback from someone from Technical Writing if that's a good idea or not.
Who can address the issue
As the first step, I suggest we find volunteers for the existing pages of the front end. We don't have to cover all of them. If there are not enough maintainers, we can think of merging some sections under the same root. If you would like to participate, feel free to add your name to the table here. The details on the next steps will follow once we clarify the options we have for technical integration of the maintainers into reviewing process (see this comment)
Here is the table to track the progress: