Further document the role of the Technical Writing team regarding contributor-focused docs
There have been simultaneous discussions about clarifying and documenting Technical Writing work across:
- The
gitlab
project's /doc/development section (within the team, as we reallocate assignments) -
gitlab-ui
gitlab-ui#598 (closed) - Pajamas Design System #93 (closed)
Proposal
I just discussed an MVC handbook update with @marcia regarding the role of the TW team on these in light of the other linked discussions and further feedback she shared on her experience with these docs. I suggested that we begin by expanding @marcia's Tech Writing counterpart role for /doc/development to Pajamas and the gitlab-ui project, but for each, we'll also specify the requirements and roles of TW more broadly, which may not always require a technical writer reviewer. Specifically:
- For Pajamas, the Tech Writing team always reviews /content section MRs. In the future this could fall to a TW Style DRI or team subgroup via roulette, but we can start by defaulting to Marcia. The exception will be cases where the style is Product-specific, in which case the Stage tech writer is required to review.
- For gitlab-ui, the Tech Writing team will not review changes by default, but can otherwise be of help e.g. helping establish templates and process (in line with the discussion here gitlab-ui#598 (closed)). Marcia will be taking this on.
- For /doc/development, Marcia will continue to review all MRs, due to the importance of maintaining high quality, accessible contributing docs for the entire GitLab community, including potential partners.
In each case, the TW counterpart can be of further help on request, beyond the minimum requirements, and we should consider opportunities to further share the work so that Marcia maintains enough bandwidth to cover her product stage, as well.
Open to any comments. Meanwhile next steps are below.
Plan
-
Marcia to raise MVC MR reflecting the above to the second table here https://about.gitlab.com/handbook/engineering/technical-writing/#assignments and its footnote(s). => gitlab-com/www-gitlab-com!42354 (merged) -
Once merged, follow-up MRs for relevant docs specific to each area to cover process and cross-link with https://about.gitlab.com/handbook/engineering/technical-writing/#assignments, while working to remove any duplication.