diff options
Diffstat (limited to 'doc/development/documentation')
| -rw-r--r-- | doc/development/documentation/index.md | 39 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/index.md | 6 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/release_process.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide.md | 69 | ||||
| -rw-r--r-- | doc/development/documentation/workflow.md | 119 |
5 files changed, 173 insertions, 62 deletions
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 7d575e9b0b1..61e42ecfe83 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -30,6 +30,23 @@ The source of the documentation exists within the codebase of each GitLab applic Documentation issues and merge requests are part of their respective repositories and all have the label `Documentation`. +### Branch naming + +The [CI pipeline for the main GitLab project](../pipelines.md) is configured to automatically +run only the jobs that match the type of contribution. If your contribution contains +**only** documentation changes, then only documentation-related jobs will be run, and +the pipeline will complete much faster than a code contribution. + +If you are submitting documentation-only changes to Runner, Omnibus, or Charts, +the fast pipeline is not determined automatically. Instead, create branches for +docs-only merge requests using the following guide: + +| Branch name | Valid example | +|:----------------------|:-----------------------------| +| Starting with `docs/` | `docs/update-api-issues` | +| Starting with `docs-` | `docs-update-api-issues` | +| Ending in `-docs` | `123-update-api-issues-docs` | + ## Contributing to docs [Contributions to GitLab docs](workflow.md) are welcome from the entire GitLab community. @@ -41,7 +58,7 @@ However, anyone can contribute [documentation improvements](improvement-workflow ## Markdown and styles [GitLab docs](https://gitlab.com/gitlab-org/gitlab-docs) uses [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown) -as its markdown rendering engine. See the [GitLab Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) for a complete Kramdown reference. +as its Markdown rendering engine. See the [GitLab Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) for a complete Kramdown reference. Adhere to the [Documentation Style Guide](styleguide.md). If a style standard is missing, you are welcome to suggest one via a merge request. @@ -382,7 +399,7 @@ merge request with new or changed docs is submitted, are: - The `CHANGELOG.md` does not contain duplicate versions. - No files in `doc/` are executable. - No new `README.md` was added. - - [`markdownlint`](#markdownlint). + - [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: @@ -403,7 +420,7 @@ help you catch common issues before raising merge requests for review of documen The following are some suggested linters you can install locally and sample configuration: - [`proselint`](#proselint) -- [`markdownlint`](#markdownlint), which is the same as the test run in [`docs-lint`](#testing) +- [markdownlint](#markdownlint), which is the same as the test run in [`docs-lint`](#testing) NOTE: **Note:** This list does not limit what other linters you can add to your local documentation writing toolchain. @@ -447,18 +464,18 @@ noise. The following sample `proselint` configuration disables these checks: A file with `proselint` configuration must be placed in a [valid location](https://github.com/amperser/proselint#checks). For example, `~/.config/proselint/config`. -#### `markdownlint` +#### markdownlint -[`markdownlint`](https://github.com/DavidAnson/markdownlint) checks that markdown +[markdownlint](https://github.com/DavidAnson/markdownlint) checks that Markdown syntax follows [certain rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules), and is used by the [`docs-lint` test](#testing) with a [configuration file](#markdownlint-configuration). Our [Documentation Style Guide](styleguide.md#markdown) and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) elaborate on which choices must be made when selecting Markdown syntax for GitLab documentation. This tool helps catch deviations from those guidelines. -`markdownlint` can be used [on the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--), +markdownlint can be used [on the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--), either on a single Markdown file or on all Markdown files in a project. For example, to run -`markdownlint` on all documentation in the [`gitlab` project](https://gitlab.com/gitlab-org/gitlab), +markdownlint on all documentation in the [`gitlab` project](https://gitlab.com/gitlab-org/gitlab), run the following commands from within your `gitlab` project root directory, which will automatically detect the [`.markdownlint.json`](#markdownlint-configuration) config file in the root of the project, and test all files in `/doc` and its subdirectories: @@ -473,7 +490,7 @@ If you wish to use a different config file, use the `-c` flag: markdownlint -c <config-file-name> 'doc/**/*.md' ``` -`markdownlint` can also be run from within text editors using [plugins/extensions](https://github.com/DavidAnson/markdownlint#related), +markdownlint can also be run from within text editors using [plugins/extensions](https://github.com/DavidAnson/markdownlint#related), such as: - [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint) @@ -485,9 +502,9 @@ is in use in the four repos that are the sources for <https://docs.gitlab.com>. plugin/extension has different requirements regarding the configuration file, which is explained in each editor's docs. -##### `markdownlint` configuration +##### markdownlint configuration -Each formatting issue that `markdownlint` checks has an associated +Each formatting issue that markdownlint checks has an associated [rule](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules). These rules are configured in the `.markdownlint.json` files located in the root of four repos that are the sources for <https://docs.gitlab.com>: @@ -501,7 +518,7 @@ By default all rules are enabled, so the configuration file is used to disable u 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. +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 bf873995e54..8a5018df9b7 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -128,9 +128,9 @@ We can then loop over the `versions` array with something like: Note that the data file must have the `yaml` extension (not `yml`) and that we reference the array with a symbol (`:versions`). -## Bumping versions of CSS and Javascript +## Bumping versions of CSS and JavaScript -Whenever the custom CSS and Javascript files under `content/assets/` change, +Whenever the custom CSS and JavaScript files under `content/assets/` change, make sure to bump their version in the frontmatter. This method guarantees that your changes will take effect by clearing the cache of previous files. @@ -180,7 +180,7 @@ for its search function. This is how it works: 1. On the docs side, we use a [docsearch layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/docsearch.html) which is present on pretty much every page except <https://docs.gitlab.com/search/>, which uses its [own layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/instantsearch.html). In those layouts, - there's a javascript snippet which initiates docsearch by using an API key + there's a JavaScript snippet which initiates docsearch by using an API key and an index name (`gitlab`) that are needed for Algolia to show the results. NOTE: **For GitLab employees:** diff --git a/doc/development/documentation/site_architecture/release_process.md b/doc/development/documentation/site_architecture/release_process.md index 6f723531f4c..76bd74b0bdc 100644 --- a/doc/development/documentation/site_architecture/release_process.md +++ b/doc/development/documentation/site_architecture/release_process.md @@ -117,7 +117,7 @@ version and rotates the old one: There's a temporary hack for now: 1. Edit `content/404.html`, making sure all offline versions under - `content/_data/versions.yaml` are in the Javascript snippet at the end of + `content/_data/versions.yaml` are in the JavaScript snippet at the end of the document. 1. **Update the `:latest` and `:archives` Docker images:** diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index e6d666473c3..385569fc8fa 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -102,7 +102,7 @@ Note that Kramdown-specific markup (e.g., `{:.class}`) will not render properly Hard-coded HTML is valid, although it's discouraged to be used while we have `/help`. HTML is permitted as long as: -- There's no equivalent markup in markdown. +- There's no equivalent markup in Markdown. - Advanced tables are necessary. - Special styling is required. - Reviewed and approved by a technical writer. @@ -111,11 +111,38 @@ Hard-coded HTML is valid, although it's discouraged to be used while we have `/h GitLab ensures that the Markdown used across all documentation is consistent, as well as easy to review and maintain, by [testing documentation changes](index.md#testing) with -[`markdownlint`](index.md#markdownlint). This lint test fails when any document has an issue +[markdownlint](index.md#markdownlint). This lint test fails when any document has an issue with Markdown formatting that may cause the page to render incorrectly within GitLab. It will also fail when a document is using non-standard Markdown (which may render correctly, but is not the current standard for GitLab documentation). +#### Markdown rule `MD044/proper-names` (capitalization) + +A rule that could cause confusion is `MD044/proper-names`, as it might not be immediately +clear what caused markdownlint to fail, or how to correct the failure. This rule +checks a list of known words, listed in the `.markdownlint.json` file in each project, +to verify that proper capitalization and backticks are used. Words in backticks will +be ignored by markdownlint. + +In general, product names should follow the exact capitalization of the official names +of the products, protocols, etc. + +Some examples that will fail if incorrect capitalization is used: + +- MinIO (needs capital `IO`) +- NGINX (needs all capitals) +- runit (needs lowercase `r`) + +Additionally, commands, parameters, values, filenames, etc. must be included in backticks. +For example: + +- "Change the `needs` keyword in your `.gitlab.yml`..." + - `needs` is a parameter, and `.gitlab.yml` is a file, so both need backticks. Additionally, + `.gitlab.yml` will fail markdownlint without backticks as it does not have capital G or L. +- "Run `git clone` to clone a Git repository..." + - `git clone` is a command, so it must be lowercase, while Git is the product, so + it must have a capital G. + ## Structure ### Organize by topic, not by type @@ -212,7 +239,7 @@ 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"). +- Do not write in the first person singular. Instead of "I" or "me," use "we," "you," "us," or "one." - Be clear, concise, and stick to the goal of the doc. - Write in US English with US grammar. - Capitalize "G" and "L" in GitLab. @@ -230,22 +257,27 @@ Do not include the same information in multiple places. [Link to a SSOT instead. "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." + - Instead of "after you execute this command, GitLab will display the result", use "after you execute this command, GitLab displays the result". - 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." + - Instead of "don't," "can't," "doesn't," and so on, use "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. + - Instead of "and/or," consider using "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." +- We recommend avoiding Latin abbreviations, such as "e.g.," "i.e.," or "etc.," +as even native users of English might misunderstand them. + - Instead of "i.e.", use "that is." + - Instead of "e.g.", use "for example." + - Instead of "etc.", either use "and so on" or consider editing it out, since it can be vague. ## Text -- [Write in markdown](#markdown). +- [Write in Markdown](#markdown). - Splitting long lines (preferably up to 100 characters) can make it easier to provide feedback on small chunks of text. - Insert an empty line for new paragraphs. - Use sentence case for titles, headings, labels, menu items, and buttons. @@ -453,7 +485,7 @@ to mix types, that is also possible, as long as you don't mix items at the same ## Quotes -Valid for markdown content only, not for frontmatter entries: +Valid for Markdown content only, not for frontmatter entries: - Standard quotes: double quotes (`"`). Example: "This is wrapped in double quotes". - Quote within a quote: double quotes (`"`) wrap single quotes (`'`). Example: "I am 'quoting' something within a quote". @@ -464,7 +496,7 @@ For other punctuation rules, please refer to the ## Headings - Add **only one H1** in each document, by adding `#` at the beginning of - it (when using markdown). The `h1` will be the document `<title>`. + it (when using Markdown). The `h1` will be the document `<title>`. - Start with an `h2` (`##`), and respect the order `h2` > `h3` > `h4` > `h5` > `h6`. Never skip the hierarchy level, such as `h2` > `h4` - Avoid putting numbers in headings. Numbers shift, hence documentation anchor @@ -490,7 +522,7 @@ For other punctuation rules, please refer to the ## Links -- Use inline link markdown markup `[Text](https://example.com)`. +- Use inline link Markdown markup `[Text](https://example.com)`. It's easier to read, review, and maintain. **Do not** use `[Text][identifier]`. - Use [meaningful anchor texts](https://www.futurehosting.com/blog/links-should-have-meaningful-anchor-text-heres-why/). @@ -533,7 +565,7 @@ For other punctuation rules, please refer to the [issue tags](../../issues/tags.md#stages) ``` -- Using the markdown extension is necessary for the [`/help`](index.md#gitlab-help) +- Using the Markdown extension is necessary for the [`/help`](index.md#gitlab-help) section of GitLab. ### Links requiring permissions @@ -656,7 +688,7 @@ to readers. To embed a video, follow the instructions below and make sure you have your MR reviewed and approved by a technical writer. -1. Copy the code below and paste it into your markdown file. +1. Copy the code below and paste it into your Markdown file. Leave a blank line above and below it. Do NOT edit the code (don't remove or add any spaces, etc). 1. On YouTube, visit the video URL you want to display. Copy @@ -694,12 +726,12 @@ This is how it renders on the GitLab Docs site: class is necessary to make sure the video is responsive and displays nicely on different mobile devices. > - The `<div class="video-fallback">` is a fallback necessary for GitLab's -`/help`, as GitLab's markdown processor does not support iframes. It's hidden on the docs site but will be displayed on GitLab's `/help`. +`/help`, as GitLab's Markdown processor does not support iframes. It's hidden on the docs site but will be displayed on GitLab's `/help`. ## Code blocks - Always wrap code added to a sentence in inline code blocks (`` ` ``). - E.g., `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, `only: master`. + E.g., `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, `only: [master]`. File names, commands, entries, and anything that refers to code should be added to code blocks. To make things easier for the user, always add a full code block for things that can be useful to copy and paste, as they can easily do it with the button on code blocks. @@ -725,7 +757,7 @@ nicely on different mobile devices. ``` ~~~ -- To display raw markdown instead of rendered markdown, you can use triple backticks +- To display raw Markdown instead of rendered Markdown, you can use triple backticks with `md`, like the `Markdown code` example above, unless you want to include triple backticks in the code block as well. In that case, use triple tildes (`~~~`) instead. - For a complete reference on code blocks, check the [Kramdown guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/#code-blocks). @@ -739,7 +771,7 @@ _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 +Within GitLab itself, they will appear as plain Markdown text (like the examples above the rendered versions, below). ### Note @@ -1055,7 +1087,7 @@ 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: +When documenting feature flags for a feature, include: - Why a feature flag is necessary. Some of the reasons are [outlined in the handbook](https://about.gitlab.com/handbook/product/#alpha-beta-ga). @@ -1080,6 +1112,9 @@ Feature.disable(:feature_flag) ``` ```` +For guidance on developing with feature flags, see +[Feature flags in development of GitLab](../feature_flags/index.md). + ## API Here is a list of must-have items. Use them in the exact order that appears diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index c373b976453..e48c940dc21 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -15,12 +15,31 @@ documentation is associated with: 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. +## Documentation labels + +Regardless of the type of issue or merge request, certain labels are required when documentation +is added or updated. The following are added by the issue or merge request author: + +- An appropriate [type label](../contributing/issue_workflow.md#type-labels). For example, + `~backstage`. +- The [stage label](../contributing/issue_workflow.md#stage-labels) and + [group label](../contributing/issue_workflow.md#group-labels). For example, `~devops::create` and + `~group::source code`. +- The `~documentation` [specialization label](../contributing/issue_workflow.md#specialization-labels). + +The following are also added by members of the Technical Writing team: + +- A documentation [scoped label](../../user/project/labels.md#scoped-labels-premium) with the + `docs::` prefix. For example, `~docs::improvement`. +- The `~Technical Writing` [team label](../contributing/issue_workflow.md#team-labels). + ## 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. +- Created or updated as part of feature development, almost always in the same merge request as the + feature code. Including documentation in the same merge request as the code eliminates the + possibility that code and documentation get out of sync. - 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. @@ -100,28 +119,10 @@ Prior to merging, documentation changes committed by the developer must be revie - 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. +- The Technical Writer for the DevOps stage group, except in exceptional circumstances where a + [post-merge review](#post-merge-reviews) can be requested. - 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) @@ -149,10 +150,12 @@ will do the following: Technical Writers are responsible for: +- Participating in issues discussions and reviewing MRs for the upcoming milestone. - 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. +- Reviewing all significant new and updated documentation content, whether before merge or after it + is merged. - Assisting the developer and Product Manager with feature documentation delivery. ##### Planning @@ -228,7 +231,7 @@ 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. +Developers, Technical Writers, and others may help further refine this plan at any time on request. The following details should be included: @@ -283,13 +286,23 @@ To update GitLab documentation: 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: +Request help from the Technical Writing team 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. +To request help: + +1. Locate the the Technical Writer for the relevant + [DevOps stage group](https://about.gitlab.com/handbook/product/technical-writing/index.html#assignments). +1. Either: + - If urgent help is required, directly assign the Technical Writer in the issue or + [in the merge request](../../user/project/merge_requests/creating_merge_requests.md#multiple-assignees-starter). + - If non-urgent help is required, ping the Technical Writer in the issue or merge request. + +If you are a member of GitLab's Slack workspace, you can request help in `#docs`. + ### Reviewing and merging Anyone with Maintainer access to the relevant GitLab project can merge documentation changes. @@ -307,11 +320,10 @@ The process involves the following: 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: + post-merge. Schedule post-merge reviews only if an urgent merge is required. 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. + - Post-merge review, see [Post-merge reviews](#post-merge-reviews). - Maintainer. For merge requests, Maintainers: - Can always request any of the above reviews. - Review before or after a Technical Writer review. @@ -319,7 +331,7 @@ The process involves the following: - 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, + [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** @@ -330,3 +342,50 @@ The process is reflected in the **Documentation** 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. + +## Post-merge reviews + +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. + +Circumstances where a regular pre-merge Technical Writer review might be skipped include: + +- There is a short amount of time left before the milestone release. If there are less than three days + remaining, seek a post-merge review and ping the writer via Slack to ensure the review is + completed as soon as possible. +- The size of the change is small and you have a high degree of confidence + that early users of the feature (for example, GitLab.com users) can easily + use the documentation as written. + +Remember: + +- At GitLab, we treat documentation like code. As with code, documentation must be reviewed to + ensure quality. +- Documentation forms part of the GitLab [definition of done](../contributing/merge_request_workflow.md#definition-of-done). +- 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 of documentation if it's important to get the + code with which it ships merged as soon as possible. In this case, the author of the original MR + will address the feedback provided by the Technical Writer in a follow-up MR. +- The Technical Writer can also help decide that documentation can be merged without Technical + writer review, with the review to occur soon after merge. + +### Before merging + +Ensure the following if skipping an initial Technical Writer review: + +- That [product badges](styleguide.md#product-badges) are applied. +- That the GitLab [version](styleguide.md#text-for-documentation-requiring-version-text) that + introduced the feature has been included. +- That changes to headings don't affect in-app hyperlinks. +- Specific [user permissions](../../user/permissions.md) are documented. +- That new documents are linked from higher-level indexes, for discoverability. +- Style guide is followed: + - For [directories and files](styleguide.md#working-with-directories-and-files). + - For [images](styleguide.md#images). + +NOTE: **Note:** +Merge requests that change the location of documentation must always be reviewed by a Technical +Writer prior to merging. |