Skip to content

Documentation process/policy updates to foster contributions to docs as SSOT

Mike Lewis requested to merge documentation-development-docs into master

Include the following points in /doc/development/documentation

  • GitLab's documentation is intended as the single source of truth (SSOT) for information about how to configure, use, and troubleshoot GitLab.
  • GitLab support engineers are among those who update GitLab docs. This should regularly occur when handling support cases, where a doc update would enable users to accomplish the tasks more successfully in the future on their own, preventing problems and the need to contact Support.
  • Support and others should use a docs-first approach; link to a new/updated doc MR in the relevant customer communication / forum reply, when possible.
  • In docs, we share any and all helpful info/processes/tips with customers, but warn them in specific terms about the potential ramifications of any mentioned actions. (There's no reason not to share 'risky' steps along with the rest of the docs.)
  • A 'Troubleshooting' section within doc pages: It's part of the default template for a new page and can freely be added to any page.
  • Documentation reviews and ‘who can merge’: depends on the type of update:
  • If it's a new troubleshooting section/item, minor correction, or other added note/caveat: If known by the author to be accurate or has been reviewed by SME, can be merged by anyone with master permissions (e.g. Support Manager). However, requests for technical writer review or assistance are always welcome.
  • Anyone with master permissions can merge docs changes, though a technical writer review can happen prior to merge. Otherwise technical writers will review all docs changes post-merge.
  • If deleting/moving a page or page subsection, and other larger doc updates, we require a technical writer review.
  • If you have ideas for further documentation resources that would be best considered/handled by technical writers, devs, and other SMEs, create an issue.
  • Additional items discussed in this doc
  • Standardization of page names
  • Better cross-linking
  • Removal of 'technical articles'
  • Enhancements to the template
  • A lot of additional streamlining/deduplication
Edited by Mike Lewis

Merge request reports