Should technical writers be involved in GitLab UI's documentation review process?
Since the introduction of a reviewers roulette in GitLab UI, we've been involving technical writers to review docs changes. This is a side-effect of copying some of GitLab's roulette rules over to GitLab UI.
Since then, there has been some discussion around the relevance of this process change.
Let's discuss this change here to decide on wether or not we should keep involving technical writers in GitLab UI.
Please vote for the solution that you feel is appropriate:
📖 Keep involving technical writers for both the initial review and the maintainer's review (and grant maintainers access to technical writers maintainers)
📄 Only involve technical writers for the initial review and drop the maintainer's review
⚒ Stop involving technical writers in GitLab UI and leave it up to engineers to review documentation changes
💡 Something else? Please elaborate in the comments!
Conclusion
After gathering a lot of great feedback in the discussions below, let's summarize the main decisions we seem to be agreeing upon.
Components documentation
We feel like technical writers reviews are not required for component-specific documentation. These documents are targeted at engineers using GitLab UI components, thus they should be reviewed by engineers.
Still, we would like to work on a set of guidelines for documenting components, these guidelines will be defined with the help of a technical writer (probably @marcia). We have listed a few items that could fit in those new guidelines in #587 (closed) already.
General documentation
The documentation located in the doc/
directory helps us define more general guidelines for the project. The new documentation guidelines mentioned above will most certainly be placed in this directory. We would still like to involve technical writers to review those guidelines because of their less technical nature. It shouldn't result in a big workload for TWs as those documents rarely change. Those changes would only require a single TW reviewer, the maintainer-review would be done by one of GitLab UI's current maintainers.
Action items
-
Update the reviewers roulette to stop -
1st iteration: completely remove TWs from the roulette => !1110 (merged) -
2nd iteration: reintroduce TWs in the roulette. The rule should be limited to the doc/
directory and should not suggest a maintainer => #632 (closed)
-
-
Create a follow-up issue to define GitLab UI's documentation guidelines => #624 (closed)