Documentation recent updates
Let's use this issue to link from the company call agenda with the more recent and important updates and give room for questions and feedback in this thread.
%12.1
Recent updates on the GitLab Documentation:Process:
- The docs team is no longer under the Product team, it's now part of the UX team.
- Documentation process: all user-facing changes must be documented, and all documentation additions/changes must be reviewed by a technical writer. Changes that impact the way any user or administrator uses the product, the documentation must be updated.
- For fixing typos, broken links, and very minor fixes in the docs, a maintainer can merge the MR without the tech writer review/approval. If you're unsure whether the change needs the tech writer's review, do ask for a review.
- For MR reviews, directly assign the MR to the [designated tech writer] instead of pinging them, as soon as the documentation is ready. If both the code and docs are ready, it's good to assign both the code and docs reviewers at the same time, for efficiency. Remember to give them time enough to review. If it takes more than 2 working days for a tech writer to respond, a maintainer can merge the MR as long as a post-merge review issue has been created and assigned to the tech writer. [tba: link to handbook when gitlab-com/www-gitlab-com!24952 (merged) gets merged]
- Feel free to, besides documentation, also request tech writing review for UI microcopies, error messages, and any user-facing content.
Codebase:
- We are finishing the process of merging CE and EE docs as a single codebase. All docs must be submitted to GitLab CE (including EE-only docs).
-
Product tier badges MUST be included in new/updated documentation for EE-only features. Note that we changed the syntax to use
()
instead of[]
: was**[PREMIUM]**
, changed to**(PREMIUM)**
. - Images guidelines: all images should include the GL release version in the filename (e.g.,
pipelines_v11_1.png
). (https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/29713, https://gitlab.com/gitlab-org/gitlab-ce/issues/61027). For GitLab 12.2 and above, this guideline will be a hard requirement for all images, but please start doing this from now on. - Videos: tutorials or feature overviews are very welcome to the docs. If you made a video explaining how a feature works or showing how to do something in GitLab, open an MR to the subject-related CE document with the video and assign a tech writer for review. Linked and embedded videos are supported. See https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/472, https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/29683 for reference.
- Please check the documentation structure and template.
Edited by Marcia Ramos