Documentation

GitLab’s documentation is crafted to help users, admins, and decision-makers learn about GitLab features and to optimally implement and use GitLab to meet their DevOps needs.

The documentation is an essential part of the product. Its source is developed and stored with the product in its respective paths within the GitLab CE, EE, Runner, and Omnibus repositories. It is published at docs.gitlab.com (offering multiple versions of all products’ documentation) and at the /help/ path on each GitLab instance’s domain, with content for that instance’s version and edition.

It is GitLab’s goal to create documentation that is complete, accurate, and easy to use. It should be easy to browse or search for the information you need, and easy to contribute to the documentation itself.

On this page

Documentation as Single Source of Truth (SSOT)

The documentation is the SSOT for all information related to the implementation, usage, and troubleshooting of GitLab products and features. It evolves continually in keeping with new products and features, and with improvements for clarity, accuracy, and completeness.

We include any and all information that may be helpful to the aforementioned goals. This may include (or may link to) helpful content that was not created specifically for the documentation, including presentations, diagrams, videos, etc.

We do not withhold workarounds for a single release/time period/niche case, or code that could be construed as dangerous to run, provided that we offer fully detailed warnings and context alongside it. This kind of content should be included in the docs for applicable products/versions, as it could be helpful to others and, when properly explained, its benefits outweigh the risks. If you think you have found an exception to this rule, contact the Technical Writing team.

This policy prevents information silos, ensuring that it remains easy to find information about GitLab products.

Docs-first methodology

We employ a docs-first methodology to help ensure that the docs remain a complete and trusted resource, and to make communicating about the use of GitLab more efficient.

New information that would be useful toward the future usage or troubleshooting of GitLab should not be written directly in a forum or other messaging system, but added to a docs MR and then referenced, as described above. Note that among any other doc changes, you can always add a Troubleshooting section to a doc if none exists, or un-comment and use the placeholder Troubleshooting section included as part of our doc template, if present

The more we reflexively add useful information to the docs, the more (and more successfully) the docs will be used to efficiently accomplish tasks and solve problems.

If you have questions when considering, authoring, or editing docs, ask the Technical Writing team on Slack in #docs or in GitLab by mentioning the writer for the applicable DevOps stage. Otherwise, forge ahead with your best effort. It does not need to be perfect; the team is happy to review and improve upon your content. Please review the documentation process before you begin your first documentation MR.

Who contributes to the documentation

Everyone can contribute. For documentation needs resulting from the development and release of new or enhanced features, the developer responsible for the code writes or updates the docs.

Technical writers monitor the planning and merging of documentation, reviewing all changes after they are merged, unless they are brought in to the process earlier for specific questions, reviews, or projects.

For more information on these processes, see the Documentation section of our Development docs.

Who merges the documentation and when

Anyone with master access at GitLab is welcome to merge documentation changes to GitLab's master branches, provided they believe the content is:

GitLab's technical writers review all merged content to confirm it is clear, and meets the structure/style guidelines, often making further improvements.

Note that documentation does not need to be perfect in structure and style to merge. It is better to publish an improved doc (simply better than what's currently there) and later refine it than to hold the doc in a review process where users do not know it exists or are using an inferior version of the doc.

However, if you know or suspect that a doc has been merged while in need of further enhancement, please create another MR or issue for this work.

For more information, see the Documentation section of our Development docs.

Resources about documentation

There is this handbook page, and the Documentation Guidelines that contain:

  1. Documentation Workflow
  2. Documentation Structure
  3. Documentation Style Guide
  4. Documentaion site architecture

There is also the Documentation Markdown Guide and the GitLab Docs project which contains the code that pulls the documentation content from multiple repositories and builds docs.gitlab.com

The Technical Writing team

For more information on the team and how it works to continually improve GitLab docs, see Technical Writing in the Product section of the handbook.