diff options
Diffstat (limited to 'doc/development/documentation')
| -rw-r--r-- | doc/development/documentation/feature-change-workflow.md | 177 | ||||
| -rw-r--r-- | doc/development/documentation/improvement-workflow.md | 62 | ||||
| -rw-r--r-- | doc/development/documentation/index.md | 103 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/index.md | 6 | ||||
| -rw-r--r-- | doc/development/documentation/structure.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide.md | 178 | ||||
| -rw-r--r-- | doc/development/documentation/workflow.md | 336 |
7 files changed, 529 insertions, 335 deletions
diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md index 4512b0fc987..004d8833e63 100644 --- a/doc/development/documentation/feature-change-workflow.md +++ b/doc/development/documentation/feature-change-workflow.md @@ -1,178 +1,5 @@ --- -description: How to add docs for new or enhanced GitLab features. +redirect_to: 'workflow.md' --- -# Documentation process for feature changes - -At GitLab, developers contribute new or updated documentation along with their code, but product managers and technical writers also have essential roles in the process. - -- **Developers**: Author/update documentation in the same MR as their code, and - merge it by the feature freeze for the assigned milestone. Request technical writer - assistance if needed. Other developers typically act as reviewers. -- **Product Managers** (PMs): In the issue for all new and enhanced features, - confirm the documentation requirements, plus the mentioned feature description - and use cases, which can be reused in docs. They can bring in a technical - writer for discussion or collaboration, and can be called upon themselves as a doc reviewer. -- **Technical Writers**: Review doc requirements in issues, track issues and MRs - that contain docs changes, help with any questions throughout the authoring/editing process, - work on special projects related to the documentation, and review all new and updated - docs content, whether before or after it is merged. - -Beyond this process, any member of the GitLab community can also author or request documentation -improvements that are not associated with a new or changed feature. See the [Documentation improvement workflow](improvement-workflow.md). - -## When documentation is required - -Documentation must be delivered whenever: - -- A new or enhanced feature is shipped that impacts the user/admin experience. -- There are changes to the UI or API. -- A process, workflow, or previously documented feature is changed. -- A feature is deprecated or removed. - -For example, a UI restyling that offers no difference in functionality may require -documentation updates if screenshots are now needed, or need to be updated. - -Documentation is not required when a feature is changed on the backend -only and does not directly affect the way that any user or administrator would -interact with GitLab. - -NOTE: **Note:** -When revamping documentation, if unrelated to the feature change, this should be submitted -in its own MR (using the [documentation improvement workflow](improvement-workflow.md)) -so that we can ensure the more time-sensitive doc updates are merged with code by the freeze. - -## Documentation requirements in feature issues - -Requirements for the documentation of a feature should be included as part of the -issue for planning that feature, in a Documentation section within the issue description. - -This section is provided as part of the Feature Proposal template and should be added -to the issue if it is not already present. - -Anyone can add these details, but the product manager who assigns the issue to a specific release -milestone will ensure these details are present and finalized by the time of that milestone's kickoff. -Developers, technical writers, and others may help further refine this plan at any time. - -### Details to include - -- What concepts and procedures should the docs guide and enable the user to understand or accomplish? -- To this end, what new page(s) are needed, if any? What pages/subsections need updates? Consider user, admin, and API doc changes and additions. -- For any guide or instruction set, should it help address a single use case, or be flexible to address a certain range of use cases? -- Do we need to update a previously recommended workflow? Should we link the new feature from various relevant locations? Consider all ways documentation should be affected. -- Are there any key terms or task descriptions that should be included so that the docs are found in relevant searches? -- Include suggested titles of any pages or subsections, if applicable. - -## Documenting a new or changed feature - -To follow a consistent workflow every month, documentation changes -involve the Product Managers, the developer who shipped the feature, -and the technical writer for the DevOps stage. Each role is described below. - -The Documentation items in the GitLab CE/EE [Feature Proposal issue template](https://gitlab.com/gitlab-org/gitlab/raw/master/.gitlab/issue_templates/Feature%20proposal.md) -and default merge request template will assist you with following this process. - -### Product Manager role - -For issues requiring any new or updated documentation, the Product Manager (PM) -must: - -- Add the `Documentation` label. -- Confirm or add the [documentation requirements](#documentation-requirements-in-feature-issues). -- Ensure the issue contains any new or updated feature name, overview/description, - and use cases, as required per the [documentation structure and template](structure.md), when applicable. - -Everyone is encouraged to draft the requirements in the issue, but a product manager will -do the following: - -- When the issue is assigned a release milestone, review and update the Documentation details. -- By the kickoff, finalize the Documentation details. - -### Developer and maintainer roles - -#### Authoring - -As a developer, if a ~feature issue also contains the ~Documentation label, you must ship the new or updated documentation with the code of the feature. The documentation is an essential part of the product. -Technical writers are happy to help, as requested and planned on an issue-by-issue basis. - -For feature issues requiring documentation, follow the process below unless otherwise agreed with the product manager and technical writer for a given issue: - -- Include any new and edited docs in the MR introducing the code. -- Use the Documentation requirements confirmed by the Product Manager in the - issue and discuss any further doc plans or ideas as needed. - - If the new or changed doc requires extensive collaboration or conversation, a separate, - linked issue can be used for the planning process. - - We are trying to avoid using a separate MR, so that the docs stay with the code, but the - Technical Writing team is interested in discussing any potential exceptions that may be suggested. -- Use the [Documentation guidelines](index.md), as well as other resources linked from there, - including the Documentation [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). -- If you need any help to choose the correct place for a doc, discuss a documentation - idea or outline, or request any other help, ping the Technical Writer for the relevant - [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages) - in your issue or MR, or write within `#docs` on the GitLab Slack. -- If you are working on documentation in a separate MR, ensure that if the code is merged by the 17th, the docs are as well, per the [Engineering Workflow](https://about.gitlab.com/handbook/engineering/workflow/). If the docs are not ready, the PM can approve merging the code if the engineer and tech writer commit to get documentation merged by the 21st. Otherwise the feature is not considered complete, and should not be merged. -- A policy for documenting feature-flagged - issues is forthcoming and you are welcome to join the [discussion](https://gitlab.com/gitlab-org/gitlab-foss/issues/56813). - -#### Reviews and merging - -All reviewers can help ensure accuracy, clarity, completeness, and adherence to the plans in the issue, as well as the [Documentation Guidelines](index.md) and [Style Guide](styleguide.md). - -- **Prior to merging**, documentation changes committed by the developer must be reviewed by: - - 1. **The code reviewer** for the MR, to confirm accuracy, clarity, and completeness. - 1. Optionally: Others involved in the work, such as other devs or the PM. - 1. Optionally: The technical writer for the DevOps stage. If not prior to merging, the technical writer will review after the merge. - This helps us ensure that the developer has time to merge good content by the freeze, and that it can be further refined by the release, if needed. - - To decide whether to request this review before the merge, consider the amount of time left before the code freeze, the size of the change, - and your degree of confidence in having users of an RC use your docs as written. - - Pre-merge tech writer reviews should be most common when the code is complete well in advance of the freeze and/or for larger documentation changes. - - You can request a review and if there is not sufficient time to complete it prior to the freeze, - the maintainer can merge the current doc changes (if complete) and create a follow-up doc review issue. - - The technical writer can also help decide what docs to merge before the freeze and whether to work on further changes in a follow up MR. - - **To request a pre-merge technical writer review**, assign the writer listed for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). - - **To request a post-merge technical writer review**, [create an issue for one using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-foss/issues/new?issuable_template=Doc%20Review) and link it from the MR that makes the doc change. - 1. **The maintainer** who is assigned to merge the MR, to verify clarity, completeness, and quality, to the best of their ability. - -- Upon merging, if a technical writer review has not been performed and there is not yet a linked issue for a follow-up review, the maintainer should [create an issue using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-foss/issues/new?issuable_template=Doc%20Review), link it from the MR, and - mention the original MR author in the new issue. Alternatively, the maintainer can ask the MR author to create and link this issue before the MR is merged. - -- After merging, documentation changes are reviewed by: - - 1. The technical writer -- **if** their review was not performed prior to the merge. - 1. Optionally: by the PM (for accuracy and to ensure it's consistent with the vision for how the product will be used). - Any party can raise the item to the PM for review at any point: the dev, the technical writer, or the PM, who can request/plan a review at the outset. - -### Technical Writer role - -#### Planning - -- The technical writer monitors the documentation needs of issues assigned to the current and next milestone - for their DevOps stage(s), and participates in any needed discussion on docs planning and requirements refinement - with the dev, PM, and others. -- The technical writer will review these requirements again upon the kickoff and provide feedback, as needed. - This is not a blocking review and developers should not wait to work on docs. - -#### Collaboration - -By default, the developer will work on documentation changes independently, but -the developer, PM, or technical writer can propose a broader collaboration for -any given issue. - -Additionally, technical writers are available for questions at any time. - -#### Review - -- Technical writers provide non-blocking reviews of all documentation changes, - before or after the change is merged. However, if the docs are ready in the MR while - there's time before the freeze, the technical writer's review can commence early, on request. -- The technical writer will confirm that the doc is clear, grammatically correct, - and discoverable, while avoiding redundancy, bad file locations, typos, broken links, - etc. The technical writer will review the documentation for the following, which - the developer and code reviewer should have already made a good-faith effort to ensure: - - Clarity. - - Adherence to the plans and goals in the issue. - - Location (make sure the docs are in the correct directories and has the correct name). - - Syntax, typos, and broken links. - - Improvements to the content. - - Accordance with the [Documentation Style Guide](styleguide.md), and [Structure and Template](structure.md) doc. +This document was moved to [another location](workflow.md). diff --git a/doc/development/documentation/improvement-workflow.md b/doc/development/documentation/improvement-workflow.md index 9f3b789712f..004d8833e63 100644 --- a/doc/development/documentation/improvement-workflow.md +++ b/doc/development/documentation/improvement-workflow.md @@ -1,63 +1,5 @@ --- -description: How to improve GitLab's documentation. +redirect_to: 'workflow.md' --- -# Documentation improvement workflow - -Anyone can contribute a merge request or create an issue for GitLab's documentation. - -This page covers the process for any contributions to GitLab's docs that are -not part of feature development. If you are looking for information on updating -GitLab's docs as is required with the development and release of a new feature -or feature enhancement, see the [documentation process for feature changes](feature-change-workflow.md). - -## Who updates the docs - -Anyone can contribute! You can create a merge request with documentation -when you find errors or other room for improvement in an existing doc, or when you -have an idea for all-new documentation that would help a GitLab user or administrator -to accomplish their work with GitLab. - -## How to update the docs - -1. Click "Edit this Page" at the bottom of any page on docs.gitlab.com, or navigate to - one of the repositories and doc paths listed on the [GitLab Documentation guidelines](index.md) page. - Work in a fork if you do not have developer access to the GitLab project. -1. Follow the described standards and processes listed on that Guidelines page, - including the linked resources: the [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). -1. Follow GitLab's [Merge Request Guidelines](../contributing/merge_request_workflow.md#merge-request-guidelines). - -If you need any help to choose the correct place for a doc, discuss a documentation -idea or outline, or request any other help, ping the Technical Writer for the relevant -[DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages) -in your issue or MR, or write within `#docs` if you are a member of GitLab's Slack workspace. - -## Review and merging - -Anyone with master access to the affected GitLab project can merge documentation changes. -This person must make a good-faith effort to ensure that the content is clear -(sufficiently easy for the intended audience to navigate and understand) and -that it meets the [Documentation Guidelines](index.md) and [Style Guide](styleguide.md). - -If the author or reviewer has any questions, or would like a techncial writer's review -before merging, mention the writer who is assigned to the relevant [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). - -The process can involve the following parties/phases, and is replicated in the `Documentation` MR template for GitLab CE and EE, to help with following the process. - -**1. Primary Reviewer** - Review by a [code reviewer](https://about.gitlab.com/handbook/engineering/projects/) or other appropriate colleague to confirm accuracy, clarity, and completeness. This can be skipped for minor fixes without substantive content changes. - -**2. Technical Writer** - Optional - If not requested for this MR, must be scheduled post-merge. To request a pre-merge review, assign the writer listed for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). -To request a post-merge review, [create an issue for one using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-foss/issues/new?issuable_template=Doc%20Review) and link it from the MR that makes the doc change. - -**3. Maintainer** - -1. Review by assigned maintainer, who can always request/require the above reviews. Maintainer review can occur before or after a technical writer review. -1. Ensure a release milestone of the format XX.Y is set. If the freeze for that release has begun, add the label `pick into <XX.Y>` unless this change is not required for the release. In that case, simply change the milestone. -1. If EE and CE MRs exist, merge the EE MR first, then the CE MR. -1. After merging, if there has not been a technical writer review and an issue for a follow-up review was not already created and linked from the MR, [create the issue using the Doc Review template](https://gitlab.com/gitlab-org/gitlab-foss/issues/new?issuable_template=Doc%20Review) and link it from the MR. - -## Other ways to help - -If you have ideas for further documentation resources that would be best -considered/handled by technical writers, devs, and other SMEs, please [create an issue](https://gitlab.com/gitlab-org/gitlab-foss/issues/new?issuable_template=Documentation) -using the Documentation template. +This document was moved to [another location](workflow.md). diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 4ad24d08d17..fb0aa5130f8 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -8,19 +8,16 @@ GitLab's documentation is [intended as the single source of truth (SSOT)](https: In addition to this page, the following resources can help you craft and contribute documentation: -- [Style Guide](styleguide.md) - What belongs in the docs, language guidelines, and more. +- [Style Guide](styleguide.md) - What belongs in the docs, language guidelines, Markdown standards to follow, and more. - [Structure and template](structure.md) - Learn the typical parts of a doc page and how to write each one. -- [Workflows](workflow.md) - A landing page for our key workflows: - - [Documentation process for feature changes](feature-change-workflow.md) - Adding required documentation when developing a GitLab feature. - - [Documentation improvement workflow](improvement-workflow.md) - New content not associated with a new feature. -- [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) - A reference for the markdown implementation used by GitLab's documentation site and about.gitlab.com. -- [Site architecture](site_architecture/index.md) - How docs.gitlab.com is built. +- [Documentation process](workflow.md). +- [Markdown Guide](../../user/markdown.md) - A reference for all Markdown syntax supported by GitLab. +- [Site architecture](site_architecture/index.md) - How <https://docs.gitlab.com> is built. ## Source files and rendered web locations -Documentation for GitLab, GitLab Runner, and Omnibus is published to [docs.gitlab.com](https://docs.gitlab.com). Documentation for GitLab is also published within the application at `/help` on the domain of the GitLab instance. - -At `/help`, only help for your current edition and version is included. Help for other versions is available at docs.gitlab.com. +Documentation for GitLab, GitLab Runner, Omnibus GitLab and Charts are published to <https://docs.gitlab.com>. Documentation for GitLab is also published within the application at `/help` on the domain of the GitLab instance. +At `/help`, only help for your current edition and version is included. Help for other versions is available at <https://docs.gitlab.com/archives/>. The source of the documentation exists within the codebase of each GitLab application in the following repository locations: @@ -29,6 +26,7 @@ The source of the documentation exists within the codebase of each GitLab applic | [GitLab](https://gitlab.com/gitlab-org/gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab/tree/master/doc) | | [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/) | [`/docs`](https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs) | | [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab/tree/master/doc) | +| [Charts](https://gitlab.com/gitlab-org/charts/gitlab) | [`/doc`](https://gitlab.com/gitlab-org/charts/gitlab/tree/master/doc) | Documentation issues and merge requests are part of their respective repositories and all have the label `Documentation`. @@ -55,8 +53,8 @@ See the [Structure](styleguide.md#structure) section of the [Documentation Style Changing a document's location requires specific steps to ensure that users can seamlessly access the new doc page, whether they are accessing content -on a GitLab instance domain at `/help` or at docs.gitlab.com. Be sure to ping a -GitLab technical writer if you have any questions during the process (such as +on a GitLab instance domain at `/help` or at <https://docs.gitlab.com>. Be sure to assign a +technical writer if you have any questions during the process (such as whether the move is necessary), and ensure that a technical writer reviews this change prior to merging. @@ -132,7 +130,7 @@ land on the doc via `/help`. If the documentation page being relocated already has Disqus comments, we need to preserve the Disqus thread. -Disqus uses an identifier per page, and for docs.gitlab.com, the page identifier +Disqus uses an identifier per page, and for <https://docs.gitlab.com>, the page identifier is configured to be the page URL. Therefore, when we change the document location, we need to preserve the old URL as the same Disqus identifier. @@ -181,9 +179,9 @@ Every GitLab instance includes the documentation, which is available at `/help` (`https://gitlab.example.com/help`). For example, <https://gitlab.com/help>. There are [plans](https://gitlab.com/groups/gitlab-org/-/epics/693) to end this -practice and instead link out from the GitLab application to docs.gitlab.com URLs. +practice and instead link out from the GitLab application to <https://docs.gitlab.com> URLs. -The documentation available online on docs.gitlab.com is continuously +The documentation available online on <https://docs.gitlab.com> is continuously deployed every hour from the `master` branch of GitLab, Omnibus, and Runner. Therefore, once a merge request gets merged, it will be available online on the same day. However, they will be shipped (and available on `/help`) within the milestone assigned @@ -195,7 +193,7 @@ available online on 2018-09-15, but, as the feature freeze date has passed, if the MR does not have a "pick into 11.3" label, the milestone has to be changed to 11.4 and it will be shipped with all GitLab packages only on 2018-10-22, with GitLab 11.4. Meaning, it will only be available under `/help` from GitLab -11.4 onwards, but available on docs.gitlab.com on the same day it was merged. +11.4 onwards, but available on <https://docs.gitlab.com/> on the same day it was merged. ### Linking to `/help` @@ -271,7 +269,7 @@ For example, [GitLab.com's `/help`](https://gitlab.com/help). ## Docs site architecture See the [Docs site architecture](site_architecture/index.md) page to learn -how we build and deploy the site at [docs.gitlab.com](https://docs.gitlab.com) and +how we build and deploy the site at <https://docs.gitlab.com> and to review all the assets and libraries in use. ### Global navigation @@ -301,18 +299,18 @@ You will need to push a branch to those repositories, it doesn't work for forks. The `review-docs-deploy*` job will: -1. Create a new branch in the [gitlab-docs](https://gitlab.com/gitlab-org/gitlab-docs) - project named after the scheme: `$DOCS_GITLAB_REPO_SUFFIX-$CI_ENVIRONMENT_SLUG`, - where `DOCS_GITLAB_REPO_SUFFIX` is the suffix for each product, e.g, `ce` for - CE, etc. -1. Trigger a cross project pipeline and build the docs site with your changes - -After a few minutes, the Review App will be deployed and you will be able to -preview the changes. The docs URL can be found in two places: +1. Create a new branch in the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) + project named after the scheme: `docs-preview-$DOCS_GITLAB_REPO_SUFFIX-$CI_MERGE_REQUEST_IID`, + where `DOCS_GITLAB_REPO_SUFFIX` is the suffix for each product, e.g, `ee` for + EE, `omnibus` for Omnibus GitLab, etc, and `CI_MERGE_REQUEST_IID` is the ID + of the respective merge request. +1. Trigger a cross project pipeline and build the docs site with your changes. -- In the merge request widget -- In the output of the `review-docs-deploy*` job, which also includes the - triggered pipeline so that you can investigate whether something went wrong +In case the review app URL returns 404, this means that either the site is not +yet deployed, or something went wrong with the remote pipeline. Give it a few +minutes and it should appear online, otherwise you can check the status of the +remote pipeline from the link in the merge request's job output. +If the pipeline failed or got stuck, drop a line in the `#docs` chat channel. TIP: **Tip:** Someone with no merge rights to the GitLab projects (think of forks from @@ -345,12 +343,11 @@ If you want to know the in-depth details, here's what's really happening: 1. The job runs the [`scripts/trigger-build-docs`](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/trigger-build-docs) script with the `deploy` flag, which in turn: 1. Takes your branch name and applies the following: - - The slug of the branch name is used to avoid special characters since - ultimately this will be used by NGINX. - - The `preview-` prefix is added to avoid conflicts if there's a remote branch - with the same name that you created in the merge request. - - The final branch name is truncated to 42 characters to avoid filesystem - limitations with long branch names (> 63 chars). + - The `docs-preview-` prefix is added. + - The product slug is used to know the project the review app originated + from. + - The number of the merge request is added so that you can know by the + `gitlab-docs` branch name the merge request it originated from. 1. The remote branch is then created if it doesn't exist (meaning you can re-run the manual job as many times as you want and this step will be skipped). 1. A new cross-project pipeline is triggered in the docs project. @@ -371,20 +368,33 @@ The following GitLab features are used among others: - [Review Apps](../../ci/review_apps/index.md) - [Artifacts](../../ci/yaml/README.md#artifacts) - [Specific Runner](../../ci/runners/README.md#locking-a-specific-runner-from-being-enabled-for-other-projects) +- [Pipelines for merge requests](../../ci/merge_request_pipelines/index.md) ## Testing -We treat documentation as code, and so use tests to maintain the standards and quality of the docs. -The current tests are: - -1. `docs lint`: Check that all internal (relative) links work correctly and - that all cURL examples in API docs use the full switches. It's recommended - to [check locally](#previewing-the-changes-live) before pushing to GitLab by executing the command - `bundle exec nanoc check internal_links` on your local - [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory. In addition, - `docs-lint` also runs [`markdownlint`](#markdownlint) to ensure the - markdown is consistent across all documentation. -1. In a full pipeline, tests for [`/help`](#gitlab-help-tests). +We treat documentation as code, and so use tests in our CI pipeline to maintain the +standards and quality of the docs. The current tests, which run in CI jobs when a +merge request with new or changed docs is submitted, are: + +- [`docs lint`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/docs.gitlab-ci.yml#L48): + Runs several tests on the content of the docs themselves: + - [`lint-doc.sh` script](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh) + checks that: + - All cURL examples use the long flags (ex: `--header`, not `-H`). + - The `CHANGELOG.md` does not contain duplicate versions. + - No files in `doc/` are executable. + - No new `README.md` was added. + - [`markdownlint`](#markdownlint). + - Nanoc tests, which you can [run locally](#previewing-the-changes-live) before + pushing to GitLab by executing the command `bundle exec nanoc check internal_links` + (or `internal_anchors`) on your local [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory: + - [`internal_links`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/docs.gitlab-ci.yml#L67) + checks that all internal links (ex: `[link](../index.md)`) are valid. + - [`internal_anchors`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/docs.gitlab-ci.yml#L69) + checks that all internal anchors (ex: `[link](../index.md#internal_anchor)`) + are valid. +- If any code or the `doc/README.md` file is changed, a full pipeline will run, which + runs tests for [`/help`](#gitlab-help-tests). ### Linting @@ -490,7 +500,10 @@ four repos that are the sources for <https://docs.gitlab.com>: - <https://gitlab.com/charts/gitlab/blob/master/.markdownlint.json> By default all rules are enabled, so the configuration file is used to disable unwanted -rules, and also to configure optional parameters for enabled rules as needed. +rules, and also to configure optional parameters for enabled rules as needed. You can +also check [the issue](https://gitlab.com/gitlab-org/gitlab-foss/issues/64352) that +tracked the changes required to implement these rules, and details which rules were +on or off when `markdownlint` was enabled on the docs. ## Danger Bot diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index bb598906967..f5a12e9c216 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -18,8 +18,8 @@ from where content is sourced, the `gitlab-docs` project, and the published outp ```mermaid graph LR - A[gitlab-ce/doc] - B[gitlab-ee/doc] + A[gitlab-foss/doc] + B[gitlab/doc] C[gitlab-runner/docs] D[omnibus-gitlab/doc] E[charts/doc] @@ -68,7 +68,7 @@ the GitLab Documentation website. ## Global navigation -Read through the global navigation](global_nav.md) documentation to understand: +Read through [the global navigation documentation](global_nav.md) to understand: - How the global navigation is built. - How to add new navigation items. diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index 158e69df2a6..21219dc100a 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -32,7 +32,7 @@ For additional details on each, see the [template for new docs](#template-for-ne below. Note that you can include additional subsections, as appropriate, such as 'How it Works', 'Architecture', -and other logicial divisions such as pre- and post-deployment steps. +and other logical divisions such as pre- and post-deployment steps. ## Template for new docs diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 79797107a5b..b6ec7a858fa 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -212,15 +212,36 @@ Do not include the same information in multiple places. [Link to a SSOT instead. - Use inclusive language and avoid jargon, as well as uncommon words. The docs should be clear and easy to understand. -- Write in the 3rd person (use "we", "you", "us", "one", instead of "I" or "me"). +- Write in the 3rd person (use "we," "you," "us," "one," instead of "I" or "me"). - Be clear, concise, and stick to the goal of the doc. -- Write in US English. +- Write in US English with US grammar. - Capitalize "G" and "L" in GitLab. -- Use title case when referring to [features](https://about.gitlab.com/features/) or - [products](https://about.gitlab.com/pricing/) (e.g., GitLab Runner, Geo, - Issue Boards, GitLab Core, Git, Prometheus, Kubernetes, etc), and methods or methodologies - (e.g., Continuous Integration, Continuous Deployment, Scrum, Agile, etc). Note that - some features are also objects (e.g. "GitLab's Merge Requests support X." and "Create a new merge request for Z."). +- Use title case when referring to: + - [GitLab Features](https://about.gitlab.com/features/). For example, Issue Board, + Geo, and Runner. + - GitLab [product tiers](https://about.gitlab.com/pricing/). For example, GitLab Core + and GitLab Ultimate. + - Third-party products. For example, Prometheus, Kubernetes, and Git. + - Methods or methodologies. For example, Continuous Integration, Continuous + Deployment, Scrum, and Agile. + + NOTE: **Note:** + Some features are also objects. For example, "GitLab's Merge Requests support X" and + "Create a new merge request for Z." + +- Avoid use of the future tense: + - Instead of, "After you execute this command, the result will be displayed," say "After you execute this command, the result is displayed." + - Only use the future tense to convey when the action or result will actually occur at a future time. +- Do not use contractions: + - Instead of "don't," "can't," "doesn't," and so on, say "do not," "cannot," or "does not." + - Possible exceptions are cases when a more familiar tone is desired, such as a blog post or other casual context. +- Do not use slashes to clump different words together or as a replacement for the word "or": + - Instead of "and/or," consider saying "or," or use another sensible construction. + - Other examples include "clone/fetch," author/assignee," and "namespace/repository name." Break apart any such instances in an appropriate way. + - Exceptions to this rule include commonly accepted technical terms such as CI/CD, TCP/IP, and so on. +- Do not use "may" and "might" interchangeably: + - Use "might" to indicate the probability of something occurring. "If you skip this step, the import process might fail." + - Use "may" to indicate giving permission for someone to do something, or consider using "can" instead. "You may select either option on this screen." Or, "you can select either option on this screen." ## Text @@ -239,27 +260,13 @@ Do not include the same information in multiple places. [Link to a SSOT instead. - List item 2 ``` -### Tables overlapping the TOC - -By default, all tables have a width of 100% on docs.gitlab.com. -In a few cases, the table will overlap the table of contents (ToC). -For these cases, add an entry to the document's frontmatter to -render them displaying block. This will make sure the table -is displayed behind the ToC, scrolling horizontally: - -```md ---- -table_display_block: true ---- -``` - -## Emphasis +### Emphasis - Use double asterisks (`**`) to mark a word or text in bold (`**bold**`). - Use underscore (`_`) for text in italics (`_italic_`). - Use greater than (`>`) for blockquotes. -## Punctuation +### Punctuation Check the general punctuation rules for the GitLab documentation on the table below. Check specific punctuation rules for [lists](#lists) below. @@ -274,6 +281,20 @@ Check specific punctuation rules for [lists](#lists) below. | Always add a space before and after dashes when using it in a sentence (for replacing a comma, for example). | _You should try this - or not._ | | Always use lowercase after a colon. | _Related Issues: a way to create a relationship between issues._ | +### Placeholder text + +Often in examples, a writer will provide a command or configuration that is complete apart from +a value specific to the reader. + +In these cases, use [`<` and `>`](https://en.wikipedia.org/wiki/Usage_message#Pattern) to call out +where a reader must replace text with their own value. + +For example: + +```sh +cp <your_source_directory> <your_destination_directory> +``` + ## Lists - Always start list items with a capital letter, unless they are parameters or commands @@ -463,24 +484,58 @@ For other punctuation rules, please refer to the - Leave exactly one blank line before and after a heading. - Do not use links in headings. - Add the corresponding [product badge](#product-badges) according to the tier the feature belongs. +- Use sentence case in headings. Do not capitalize the words of the title, unless + it refers to a product feature. For example, capitalizing "issues" is acceptable in + `## What you can do with GitLab Issues`, but not in `## Closing multiple issues`. ## Links - Use inline link markdown markup `[Text](https://example.com)`. It's easier to read, review, and maintain. **Do not** use `[Text][identifier]`. -- To link to internal documentation, use relative links, not full URLs. Use `../` to - navigate to high-level directories, and always add the file name `file.md` at the - end of the link with the `.md` extension, not `.html`. - Example: instead of `[text](../../merge_requests/)`, use - `[text](../../merge_requests/index.md)` or, `[text](../../ci/README.md)`, or, - for anchor links, `[text](../../ci/README.md#examples)`. - Using the markdown extension is necessary for the [`/help`](index.md#gitlab-help) - section of GitLab. -- To link from CE to EE-only documentation, use the EE-only doc full URL. + - Use [meaningful anchor texts](https://www.futurehosting.com/blog/links-should-have-meaningful-anchor-text-heres-why/). E.g., instead of writing something like `Read more about GitLab Issue Boards [here](LINK)`, write `Read more about [GitLab Issue Boards](LINK)`. +### Links to internal documentation + +- To link to internal documentation, use relative links, not full URLs. + Use `../` to navigate to high-level directories. Links should not refer to root. + + Don't: + + ```md + [Geo Troubleshooting](https://docs.gitlab.com/ee/administration/geo/replication/troubleshooting.html) + [Geo Troubleshooting](/ee/administration/geo/replication/troubleshooting.md) + ``` + + Do: + + ```md + [Geo Troubleshooting](../../geo/replication/troubleshooting.md) + ``` + +- Always add the file name `file.md` at the end of the link with the `.md` extension, not `.html`. + + Don't: + + ```md + [merge requests](../../merge_requests/) + [issues](../../issues/tags.html) + [issue tags](../../issues/tags.html#stages) + ``` + + Do: + + ```md + [merge requests](../../merge_requests/index.md) + [issues](../../issues/tags.md) + [issue tags](../../issues/tags.md#stages) + ``` + +- Using the markdown extension is necessary for the [`/help`](index.md#gitlab-help) + section of GitLab. + ### Links requiring permissions Don't link directly to: @@ -535,7 +590,7 @@ To indicate the steps of navigation through the UI: a valid name for an illustration is `devops_diagram_v11_1.png`. - Keep all file names in lower case. - Consider using PNG images instead of JPEG. -- Compress all images with <https://tinypng.com/> or similar tool. +- Compress all images with <https://pngquant.org/> or similar tool. - Compress gifs with <https://ezgif.com/optimize> or similar tool. - Images should be used (only when necessary) to _illustrate_ the description of a process, not to _replace_ it. @@ -557,7 +612,7 @@ Inside the document: ### Remove image shadow -All images displayed on docs.gitlab.com have a box shadow by default. +All images displayed on the [GitLab Docs site](https://docs.gitlab.com) have a box shadow by default. To remove the box shadow, use the image class `.image-noshadow` applied directly to an HTML `img` tag: @@ -591,7 +646,7 @@ You can link any up-to-date video that is useful to the GitLab user. > [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/merge_requests/472) in GitLab 12.1. -GitLab docs (docs.gitlab.com) support embedded videos. +The [GitLab Docs site](https://docs.gitlab.com) supports embedded videos. You can only embed videos from [GitLab's official YouTube account](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg). @@ -627,7 +682,7 @@ leave a blank line here leave a blank line here ``` -This is how it renders on docs.gitlab.com: +This is how it renders on the GitLab Docs site: <div class="video-fallback"> See the video: <a href="https://www.youtube.com/watch?v=enMumwvLAug">What is GitLab</a>. @@ -686,6 +741,10 @@ use the following markup for highlighting. _Note that the alert boxes only work for one paragraph only. Multiple paragraphs, lists, headers, etc will not render correctly. For multiple lines, use blockquotes instead._ +Alert boxes only render on the GitLab Docs site (<https://docs.gitlab.com>). +Within GitLab itself, they will appear as plain markdown text (like the examples +above the rendered versions, below). + ### Note Notes catch the eye of most readers, and therefore should be used very sparingly. @@ -710,7 +769,7 @@ NOTE: **Note:** This is something to note. ``` -How it renders in docs.gitlab.com: +How it renders on the GitLab Docs site: NOTE: **Note:** This is something to note. @@ -722,7 +781,7 @@ TIP: **Tip:** This is a tip. ``` -How it renders in docs.gitlab.com: +How it renders on the GitLab Docs site: TIP: **Tip:** This is a tip. @@ -734,7 +793,7 @@ CAUTION: **Caution:** This is something to be cautious about. ``` -How it renders in docs.gitlab.com: +How it renders on the GitLab Docs site: CAUTION: **Caution:** This is something to be cautious about. @@ -746,7 +805,7 @@ DANGER: **Danger:** This is a breaking change, a bug, or something very important to note. ``` -How it renders in docs.gitlab.com: +How it renders on the GitLab Docs site: DANGER: **Danger:** This is a breaking change, a bug, or something very important to note. @@ -759,7 +818,7 @@ For highlighting a text within a blue blockquote, use this format: > This is a blockquote. ``` -which renders in docs.gitlab.com to: +which renders on the [GitLab Docs site](https://docs.gitlab.com) as: > This is a blockquote. @@ -992,6 +1051,38 @@ In this case: - Different highlighting languages are used for each config in the code block. - The [GitLab Restart](#gitlab-restart) section is used to explain a required restart/reconfigure of GitLab. +## Feature flags + +Sometimes features are shipped with feature flags, either: + +- On by default, but providing the option to turn the feature off. +- Off by default, but providing the option to turn the feature on. + +When documenting feature flags for a feature, it's important that users know: + +- Why a feature flag is necessary. Some of the reasons are + [outlined in the handbook](https://about.gitlab.com/handbook/product/#alpha-beta-ga). +- That administrative access is required to make a feature flag change. +- What to ask for when requesting a change to a feature flag's state. + +NOTE: **Note:** +The [Product Manager for the relevant group](https://about.gitlab.com/handbook/product/categories/#devops-stages) +must review and approve the addition or removal of any mentions of using feature flags before the doc change is merged. + +The following is sample text for adding feature flag documentation for a feature: + +````md +### Disabling the feature + +This feature comes with the `:feature_flag` feature flag enabled by default. However, in some cases +this feature is incompatible with old configuration. To turn off the feature while configuration is +migrated, ask a GitLab administrator with Rails console access to run the following command: + +```ruby +Feature.disable(:feature_flag) +``` +```` + ## API Here is a list of must-have items. Use them in the exact order that appears @@ -1100,7 +1191,7 @@ Rendered example: ### cURL Examples -Below is a set of [cURL][] examples that you can use in the API documentation. +Below is a set of [cURL](https://curl.haxx.se) examples that you can use in the API documentation. #### Simple cURL command @@ -1147,7 +1238,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "title= ``` The above example is run by and administrator and will add an SSH public key -titled ssh-key to user's account which has an id of 25. +titled `ssh-key` to user's account which has an id of 25. #### Escape special characters @@ -1172,7 +1263,6 @@ restrict the sign-up e-mail domains of a GitLab instance to `*.example.com` and curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "domain_whitelist[]=*.example.com" --data "domain_whitelist[]=example.net" https://gitlab.example.com/api/v4/application/settings ``` -[cURL]: http://curl.haxx.se/ "cURL website" [single spaces]: http://www.slate.com/articles/technology/technology/2011/01/space_invaders.html [gfm]: ../../user/markdown.md#newlines "GitLab flavored markdown documentation" [ce-1242]: https://gitlab.com/gitlab-org/gitlab-foss/issues/1242 diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 9f488fac7d0..24399391b1a 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -1,10 +1,332 @@ ---- -description: Learn the processes for contributing to GitLab's documentation. ---- +# Documentation process -# Documentation workflows +The process for creating and maintaining GitLab product documentation depends on whether the +documentation is associated with: -Documentation workflows at GitLab differ depending on the reason for the change: +- [A new feature or feature enhancement](#for-a-product-change). -- [Documentation process for feature changes](feature-change-workflow.md) - The documentation is being created or updated as part of the development and release of a new or enhanced feature. This process involves the developer of the feature (who includes new/updated documentation files as part of the same merge request containing the feature's code) and also involves the product manager and technical writer who are listed for the feature's [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). -- [Documentation improvement workflow](improvement-workflow.md) - All documentation additions not associated with a feature release. Documentation is being created or updated to improve accuracy, completeness, ease of use, or any reason other than a feature change. Anyone (and everyone) can contribute a merge request for this type of change at any time. + Delivered for a specific milestone and associated with specific code changes. This documentation + has the highest priority. + +- [Changes outside a specific milestone](#for-all-other-documentation). + + It is usually not associated with a specific code change and has a lower priority. + +Documentation is not usually required when a "backstage feature" is added or changed, and does not +directly affect the way that any user or administrator interacts with GitLab. + +## For a product change + +This documentation is required for any new or changed feature and is: + +- Created or updated as part of feature development, typically via the same merge request as the + feature code. +- Required with the delivery of a feature for a specific milestone as part of GitLab's + [definition of done](../contributing/merge_request_workflow.md#definition-of-done). +- Often linked from the release post. + +### Roles and responsibilities + +Documentation for specific milestones involves the: + +- Developer of a feature or enhancement. +- Product Manager for the group delivering the new feature or feature enhancement. +- Technical Writer assigned to the group. + +Each role is described below. + +#### Developers + +Developers are the primary author of documentation for a feature or feature enhancement. They are +responsible for: + +- Developing initial content required for a feature. +- Liaising with their Product Manager to understand what documentation must be delivered, and when. +- Requesting technical reviews from other developers within their group. +- Requesting documentation reviews from the Technical Writer + [assigned to the DevOps stage group](https://about.gitlab.com/handbook/product/technical-writing/index.html#assignments) + that is delivering the new feature or feature enhancements. + +TIP: **Tip:** +Community Contributors can ask for additional help from GitLab team members. + +##### Authoring + +Because the documentation is an essential part of the product, if a ~feature issue also contains the +~documentation label, you must ship the new or updated documentation with the code of the feature. + +Technical Writers are happy to help, as requested and planned on an issue-by-issue basis. + +For feature issues requiring documentation, follow the process below unless otherwise agreed with +the Product Manager and Technical Writer for a given issue: + +- Include any new and edited documentation, either in: + - The merge request introducing the code. + - A separate merge request raised around the same time. +- Use the [documentation requirements](#documentation-requirements) developed by the Product Manager + in the issue and discuss any further documentation plans or ideas as needed. + + If the new or changed documentation requires extensive collaboration or conversation, a + separate, linked issue can be used for the planning process. + +- Use the [Documentation guidelines](index.md), as well as other resources linked from there, + including: + - Documentation [Structure and template](structure.md) page. + - [Style Guide](styleguide.md). + - [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). +- Contact the Technical Writer for the relevant [DevOps stage](https://about.gitlab.com/handbook/product/technical-writing/index.html#assignments) + in your issue or merge request, or within `#docs` on GitLab Slack, if you: + - Need any help to choose the correct place for documentation. + - Want to discuss a documentation idea or outline. + - Want to request any other help. +- If you are working on documentation in a separate merge request, ensure the documentation is + merged as close as possible to the code merge. +- A policy for documenting [feature-flagged](../feature_flags/index.md) issues is forthcoming and you + are welcome to join the [discussion](https://gitlab.com/gitlab-org/gitlab/issues/26347). + +##### Reviews and merging + +Reviewers help ensure: + +- Accuracy. +- Clarity. +- Completeness. +- Adherence to: + - [Documentation requirements](#documentation-requirements) in the issue. + - [Documentation guidelines](index.md). + - [Style guide](styleguide.md). + +Prior to merging, documentation changes committed by the developer must be reviewed by: + +- The code reviewer for the merge request. This is known as a technical review. +- Optionally, others involved in the work, such as other developers or the Product Manager. +- Optionally, the Technical Writer for the DevOps stage group. +- A maintainer of the project. + +If not assigned to a Technical Writer for review prior to merging, a review must be scheduled +immediately after merge by the developer or maintainer. For this, +create an issue using the [Doc Review description template](https://gitlab.com/gitlab-org/gitlab/issues/new?issuable_template=Doc%20Review) +and link to it from the merged merge request that introduced the documentation change. + +To decide whether to request a Technical Writer review before or after merge, consider: + +- The amount of time left before the milestone release. If there is less than three days + remaining, seek a post-merge review and ping the writer via Slack to ensure the review is + completed in time. +- The size of the change and your degree of confidence in having early users (for example, + GitLab.com users) of features use your documentation as written. +- That pre-merge Technical Writer reviews should be most common when the code is complete well in + advance of a milestone release and for larger documentation changes. +- You can request a post-merge Technical Writer review if it's important to get the code part of + a merge request merged as soon as possible. +- The Technical Writer can also help decide that documentation can be merged without Technical + writer review, with the review to occur soon after merge. + +#### Product Managers + +Product Managers are responsible for the [documentation requirements](#documentation-requirements) +for a feature or feature enhancement. They can also: + +- Liaise with the Technical Writer for discussion and collaboration. +- Review documentation themselves. + +For issues requiring any new or updated documentation, the Product Manager must: + +- Add the ~documentation label. +- Confirm or add the [documentation requirements](#documentation-requirements). +- Ensure the issue contains: + - Any new or updated feature name. + - Overview, description, and use cases, as required by the + [documentation structure and template](structure.md), when applicable. + +Everyone is encouraged to draft the documentation requirements in the issue, but a Product Manager +will do the following: + +- When the issue is assigned a release milestone, review and update the Documentation details. +- By the kickoff, finalize the documentation details. + +#### Technical Writers + +Technical Writers are responsible for: + +- Reviewing documentation requirements in issues when called upon. +- Answering questions, and helping and providing advice throughout the authoring and editing + process. +- Reviewing all new and updated documentation content, whether before merge or after it is merged. +- Assisting the developer and Product Manager with feature documentation delivery. + +##### Planning + +The Technical Writer: + +- Reviews their group's `~feature` issues that are part of the next milestone to get a sense of the + scope of content likely to be authored. +- Recommends the `~documentation` label on issues from that list which don't have it but should, or + inquires with the PM to determine if documentation is truly required. +- For `~direction` issues from that list, reads the full issue and reviews its Documentation + requirements section. Addresses any recommendations or questions with the PMs and others + collaborating on the issue in order to refine or expand the Documentation requirements. + +##### Collaboration + +By default, the developer will work on documentation changes independently, but +the developer, Product Manager, or Technical Writer can propose a broader collaboration for +any given issue. + +Additionally, Technical Writers are available for questions at any time. + +##### Review + +Technical Writers: + +- Provide non-blocking reviews of all documentation changes, before or after the change is merged. +- Confirm that the documentation is: + - Clear. + - Grammatically correct. + - Discoverable. + - Navigable. +- Ensures that the documentation avoids: + - Redundancy. + - Bad file locations. + - Typos. + - Broken links. + +The Technical Writer will review the documentation to check that the developer and +code reviewer have ensured: + +- Clarity. +- Appropriate location, making sure the documentation is in the correct directories (often + reflecting how the product is structured) and has the correct name. +- Syntax, typos, and broken links. +- Improvements to the content. +- Accordance with the: + - [Documentation Style Guide](styleguide.md). + - [Structure and Template](structure.md) doc. + +### When documentation is required + +Documentation [is required](../contributing/merge_request_workflow.html#definition-of-done) for a +milestone when: + +- A new or enhanced feature is shipped that impacts the user of administrator experience. +- There are changes to the UI or API. +- A process, workflow, or previously documented feature is changed. +- A feature is deprecated or removed. + +NOTE: **Note:** +Documentation refactoring unrelated to a feature change is covered in the +[other process](#for-all-other-documentation), so that time-sensitive documentation updates are +prioritized. + +### Documentation requirements + +Requirements for the documentation of a feature should be included as part of the +issue for planning that feature in a **Documentation** section within the issue description. Issues +created using the [**Feature Proposal** template](https://gitlab.com/gitlab-org/gitlab/raw/master/.gitlab/issue_templates/Feature%20proposal.md) +have this section by default. + +Anyone can add these details, but the Product Manager who assigns the issue to a specific release +milestone will ensure these details are present and finalized by the time of that milestone's kickoff. + +Developers, Technical Writers, and others may help further refine this plan at any time. + +The following details should be included: + +- What concepts and procedures should the documentation guide and enable the user to understand or + accomplish? +- To this end, what new page(s) are needed, if any? What pages or subsections need updates? + Consider user, admin, and API documentation changes and additions. +- For any guide or instruction set, should it help address a single use case, or be flexible to + address a certain range of use cases? +- Do we need to update a previously recommended workflow? Should we link the new feature from + various relevant locations? Consider all ways documentation should be affected. +- Are there any key terms or task descriptions that should be included so that the documentation is + found in relevant searches? +- Include suggested titles of any pages or subsection headings, if applicable. +- List any documentation that should be cross-linked, if applicable. + +## For all other documentation + +These documentation changes are not associated with the release of a new or updated feature, and are +therefore labeled `backstage` in GitLab, rather than `feature`. They may include: + +- Documentation created or updated to improve accuracy, completeness, ease of use, or any reason + other than a [feature change](#for-a-product-change). +- Addressing gaps in existing documentation, or making improvements to existing documentation. +- Work on special projects related to the documentation. + +TIP: **Tip:** +Anyone can contribute a merge request or create an issue for GitLab's documentation. + +### Who updates the docs + +Anyone can contribute! You can create a merge request for documentation when: + +- You find errors or other room for improvement in existing documentation. +- You have an idea for all-new documentation that would help a GitLab user or administrator to + accomplish their work with GitLab. + +### How to update the docs + +To update GitLab documentation: + +1. Either: + - Click the **Edit this Page** link at the bottom of any page on <https://docs.gitlab.com>. + - Navigate to one of the repositories and documentation paths listed on the + [GitLab Documentation guidelines](index.md) page. +1. Follow the described standards and processes listed on the page, including: + - The [Structure and template](structure.md) page. + - The [Style Guide](styleguide.md). + - The [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). +1. Follow GitLab's [Merge Request Guidelines](../contributing/merge_request_workflow.md#merge-request-guidelines). + +TIP: **Tip:** +Work in a fork if you do not have developer access to the GitLab project. + +Ping the Technical Writer for the relevant [DevOps stage group](https://about.gitlab.com/handbook/product/technical-writing/index.html#assignments) +in your issue or merge request, or within `#docs` if you are a member of GitLab's Slack workspace, if you: + +- Need help to choose the correct place for documentation. +- Want to discuss a documentation idea or outline. +- Want to request any other help. + +### Reviewing and merging + +Anyone with Maintainer access to the relevant GitLab project can merge documentation changes. +Maintainers must make a good-faith effort to ensure that the content: + +- Is clear and sufficiently easy for the intended audience to navigate and understand. +- Meets the [Documentation Guidelines](index.md) and [Style Guide](styleguide.md). + +If the author or reviewer has any questions, they can mention the writer who is assigned to the relevant +[DevOps stage group](https://about.gitlab.com/handbook/product/technical-writing/index.html#assignments). + +The process involves the following: + +- Primary Reviewer. Review by a [code reviewer](https://about.gitlab.com/handbook/engineering/projects/) + or other appropriate colleague to confirm accuracy, clarity, and completeness. This can be skipped + for minor fixes without substantive content changes. +- Technical Writer (Optional). If not completed for a merge request prior to merging, must be scheduled + post-merge. To request a: + - Pre-merge review, assign the Technical Writer listed for the applicable + [DevOps stage group](https://about.gitlab.com/handbook/product/technical-writing/index.html#assignments). + - Post-merge review, [create an issue for one](https://gitlab.com/gitlab-org/gitlab/issues/new?issuable_template=Doc%20Review) + and link it from the MR that makes the documentation change. +- Maintainer. For merge requests, Maintainers: + - Can always request any of the above reviews. + - Review before or after a Technical Writer review. + - Ensure the given release milestone is set. + - Ensure the appropriate labels are applied, including any required to pick a merge request into + a release. + - Ensure that, if there has not been a Technical Writer review completed or scheduled, they + [create the required issue](https://gitlab.com/gitlab-org/gitlab/issues/new?issuable_template=Doc%20Review), assign to the technical writer of the given stage group, + and link it from the merge request. + +The process is reflected in the **Documentation** +[merge request template](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/merge_request_templates/Documentation.md). + +### Other ways to help + +If you have ideas for further documentation resources please +[create an issue](https://gitlab.com/gitlab-org/gitlab/issues/new?issuable_template=Documentation) +using the Documentation template. |