diff options
| -rw-r--r-- | .gitlab/issue_templates/Documentation.md | 54 | ||||
| -rw-r--r-- | .gitlab/merge_request_templates/Change documentation location.md | 32 | ||||
| -rw-r--r-- | .gitlab/merge_request_templates/Documentation.md | 35 | ||||
| -rw-r--r-- | PROCESS.md | 33 | ||||
| -rw-r--r-- | doc/development/documentation/index.md | 66 | ||||
| -rw-r--r-- | doc/development/documentation/structure.md | 149 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide.md | 26 | ||||
| -rw-r--r-- | doc/development/documentation/workflow.md | 186 |
8 files changed, 509 insertions, 72 deletions
diff --git a/.gitlab/issue_templates/Documentation.md b/.gitlab/issue_templates/Documentation.md new file mode 100644 index 00000000000..b33ed5bcaa8 --- /dev/null +++ b/.gitlab/issue_templates/Documentation.md @@ -0,0 +1,54 @@ +<!--See the general documentation guidelines https://docs.gitlab.com/ee/development/documentation --> + +<!-- Mention "documentation" or "docs" in the issue title --> + +<!-- Use this description template for new docs or updates to existing docs. --> + +<!-- Check the documentation structure guidelines for guidance: https://docs.gitlab.com/ee/development/documentation/structure.html--> + +- [ ] Documents Feature A <!-- feature name --> +- [ ] Follow-up from: #XXX, !YYY <!-- Mention related issues, MRs, and epics when available --> + +## New doc or update? + +<!-- Mark either of these boxes: --> + +- [ ] New documentation +- [ ] Update existing documentation + +## Checklists + +### Product Manager + +<!-- Reference: https://docs.gitlab.com/ee/development/documentation/workflow.html#1-product-manager-s-role-in-the-documentation-process --> + +- [ ] Add the correct labels +- [ ] Add the correct milestone +- [ ] Indicate the correct document/directory for this feature <!-- (ping the tech writers for help if you're not sure) --> +- [ ] Fill the doc blurb below + +#### Documentation blurb + +<!-- Documentation template: https://docs.gitlab.com/ee/development/documentation/structure.html#documentation-template-for-new-docs --> + +- Doc **title** + + <!-- write the doc title here --> + +- Feature **overview/description** + + <!-- Write the feature overview here --> + +- Feature **use cases** + + <!-- Write the use cases here --> + +### Developer + +<!-- Reference: https://docs.gitlab.com/ee/development/documentation/workflow.html#2-developer-s-role-in-the-documentation-process --> + +- [ ] Copy the doc blurb above and paste it into the doc +- [ ] Write the tutorial - explain how to use the feature +- [ ] Submit the MR using the appropriate MR description template + +/label ~Documentation diff --git a/.gitlab/merge_request_templates/Change documentation location.md b/.gitlab/merge_request_templates/Change documentation location.md new file mode 100644 index 00000000000..b4a6d2bd3b4 --- /dev/null +++ b/.gitlab/merge_request_templates/Change documentation location.md @@ -0,0 +1,32 @@ +<!--See the general Documentation guidelines https://docs.gitlab.com/ee/development/documentation/ --> + +<!-- Use this description template for changing documentation location. For new docs or updates to existing docs, use the "Documentation" template --> + +## What does this MR do? + +<!-- Briefly describe what this MR is about --> + +## Related issues + +<!-- Mention the issue(s) this MR closes or is related to --> + +Closes + +## Moving docs to a new location? + +Read the guidelines: +https://docs.gitlab.com/ce/development/documentation/index.html#changing-document-location + +- [ ] Make sure the old link is not removed and has its contents replaced with + a link to the new location. +- [ ] Make sure internal links pointing to the document in question are not broken. +- [ ] Search and replace any links referring to old docs in GitLab Rails app, + specifically under the `app/views/` and `ee/app/views` (for GitLab EE) directories. +- [ ] Make sure to add [`redirect_from`](https://docs.gitlab.com/ce/development/writing_documentation.html#redirections-for-pages-with-disqus-comments) + to the new document if there are any Disqus comments on the old document thread. +- [ ] Update the link in `features.yml` (if applicable) +- [ ] If working on CE and the `ee-compat-check` jobs fails, submit an MR to EE + with the changes as well (https://docs.gitlab.com/ce/development/writing_documentation.html#cherry-picking-from-ce-to-ee). +- [ ] Ping one of the technical writers for review. + +/label ~Documentation diff --git a/.gitlab/merge_request_templates/Documentation.md b/.gitlab/merge_request_templates/Documentation.md index 531035b3766..ca38c881c66 100644 --- a/.gitlab/merge_request_templates/Documentation.md +++ b/.gitlab/merge_request_templates/Documentation.md @@ -1,4 +1,8 @@ -<!--See the general Documentation guidelines https://docs.gitlab.com/ee/development/documentation/index.html --> +<!--See the general documentation guidelines https://docs.gitlab.com/ee/development/documentation --> + +<!-- Mention "documentation" or "docs" in the MR title --> + +<!-- Use this description template for new docs or updates to existing docs. For changing documentation location use the "Change documentation location" template --> ## What does this MR do? @@ -10,20 +14,19 @@ Closes -## Moving docs to a new location? - -Read the guidelines: -https://docs.gitlab.com/ee/development/documentation/#changing-document-location - -- [ ] Make sure the old link is not removed and has its contents replaced with - a link to the new location. -- [ ] Make sure internal links pointing to the document in question are not broken. -- [ ] Search and replace any links referring to the old docs in the GitLab Rails app, - specifically under the `app/views/` and `ee/app/views` (for GitLab EE) directories. -- [ ] Make sure to add [`redirect_from`](https://docs.gitlab.com/ee/development/documentation/index.html#redirections-for-pages-with-disqus-comments) - to the new document if there are any Disqus comments on the old document thread. -- [ ] If working on CE and the `ee-compat-check` jobs fails, [submit an MR to EE - with the changes](https://docs.gitlab.com/ee/development/documentation/index.html#cherry-picking-from-ce-to-ee) as well. -- [ ] Ping one of the technical writers for review. +## Author's checklist + +- [ ] [Apply the correct labels and milestone](https://docs.gitlab.com/ee/development/documentation/workflow.html#2-developer-s-role-in-the-documentation-process) +- [ ] Crosslink the document from the higher-level index +- [ ] Crosslink the document from other subject-related docs +- [ ] Correctly apply the product [badges](https://docs.gitlab.com/ee/development/documentation/styleguide.html#product-badges) and [tiers](https://docs.gitlab.com/ee/development/documentation/styleguide.html#gitlab-versions-and-tiers) +- [ ] [Port the MR to EE (or backport from CE)](https://docs.gitlab.com/ee/development/documentation/index.html#cherry-picking-from-ce-to-ee): _always recommended, required when the `ee-compat-check` job fails_ + +## Review checklist + +- [ ] Your team's review (required) +- [ ] PM's review (recommended, but not a blocker) +- [ ] Technical writer's review (required) +- [ ] Merge the EE-MR first, CE-MR afterwards /label ~Documentation diff --git a/PROCESS.md b/PROCESS.md index 5f50d472bd7..583f36b820f 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -116,6 +116,11 @@ target. However, if one does and falls into either of the above categories, it's the reviewer's responsibility to manage the above communication and assignment on behalf of the community member. +Every new feature or change should be shipped with its corresponding documentation +in accordance with the +[documentation process](https://docs.gitlab.com/ee/development/documentation/workflow.html) +and [structure](https://docs.gitlab.com/ee/development/documentation/structure.html). + #### What happens if these deadlines are missed? If a small or large feature is _not_ with a maintainer or reviewer by the @@ -141,14 +146,9 @@ and to prevent any last minute surprises. ### On the 7th -Merge requests should still be complete, following the -[definition of done][done]. The single exception is documentation, and this can -only be left until after the freeze if: +Merge requests should still be complete, following the [definition of done][done]. -* There is a follow-up issue to add documentation. -* It is assigned to the person writing documentation for this feature, and they - are aware of it. -* It is in the correct milestone, with the ~Deliverable label. +#### Feature merge requests If a merge request is not ready, but the developers and Product Manager responsible for the feature think it is essential that it is in the release, @@ -164,6 +164,23 @@ information, see [Automatic CE->EE merge][automatic_ce_ee_merge] and [Guidelines for implementing Enterprise Edition features][ee_features]. +#### Documentation merge requests + +Documentation is part of the product and must be shipped with the feature. + +The single exception for the feature freeze is documentation, and it can +be left to be **merged up to the 14th** if: + +* There is a follow-up issue to add documentation. +* It is assigned to the developer writing documentation for this feature, and they + are aware of it. +* It is in the correct milestone, with the labels ~Documentation, ~Deliverable, +~missed-deliverable, and "pick into X.Y" applied. +* It must be reviewed and approved by a technical writer. + +For more information read the process for +[documentation shipped late](https://docs.gitlab.com/ee/development/documentation/workflow.html#documentation-shipped-late). + ### After the 7th Once the stable branch is frozen, the only MRs that can be cherry-picked into @@ -172,7 +189,7 @@ the stable branch are: * Fixes for [regressions](#regressions) where the affected version `xx.x` in `regression:xx.x` is the current release. See [Managing bugs](#managing-bugs) section. * Fixes for security issues * Fixes or improvements to automated QA scenarios -* Documentation updates for changes in the same release +* [Documentation updates](https://docs.gitlab.com/ee/development/documentation/workflow.html#documentation-shipped-late) for changes in the same release * New or updated translations (as long as they do not touch application code) During the feature freeze all merge requests that are meant to go into the diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index f5cdd310f6f..f46c171d9f1 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -25,52 +25,23 @@ them to review it for you. We use the [monthly release blog post](https://about.gitlab.com/handbook/marketing/blog/release-posts/#monthly-releases) as a changelog checklist to ensure everything is documented. -Whenever you submit a merge request for the documentation, use the documentation MR description template. +Whenever you submit a merge request for the documentation, use the +"Documentation" MR description template. If you're changing documentation +location, use the MR description template called "Change documentation +location" instead. -Please check the [documentation workflow](https://about.gitlab.com/handbook/product/technical-writing/workflow/) before getting started. +## Documentation workflow -## Documentation structure - -- Overview and use cases: what it is, why it is necessary, why one would use it -- Requirements: what do we need to get started -- Tutorial: how to set it up, how to use it - -Always link a new document from its topic-related index, otherwise, it will -not be included it in the documentation site search. - -_Note: to be extended._ - -### Feature overview and use cases - -Every major feature (regardless if present in GitLab Community or Enterprise editions) -should present, at the beginning of the document, two main sections: **overview** and -**use cases**. Every GitLab EE-only feature should also contain these sections. +Please read through the [documentation workflow](workflow.md) before getting started. -**Overview**: as the name suggests, the goal here is to provide an overview of the feature. -Describe what is it, what it does, why it is important/cool/nice-to-have, -what problem it solves, and what you can do with this feature that you couldn't -do before. - -**Use cases**: provide at least two, ideally three, use cases for every major feature. -You should answer this question: what can you do with this feature/change? Use cases -are examples of how this feature or change can be used in real life. - -Examples: -- CE and EE: [Issues](../user/project/issues/index.md#use-cases) -- CE and EE: [Merge Requests](../user/project/merge_requests/index.md#overview) -- EE-only: [Geo](https://docs.gitlab.com/ee/gitlab-geo/README.html#overview) -- EE-only: [Jenkins integration](https://docs.gitlab.com/ee/integration/jenkins.md#overview) - -Note that if you don't have anything to add between the doc title (`<h1>`) and -the header `## Overview`, you can omit the header, but keep the content of the -overview there. +## Documentation structure -> **Overview** and **use cases** are required to **every** Enterprise Edition feature, -and for every **major** feature present in Community Edition. +Follow through the [documentation structure guide](structure.md) for learning +how to structure GitLab docs. ## Markdown and styles -Currently GitLab docs use Redcarpet as [markdown](../user/markdown.md) engine, but there's an [open discussion](https://gitlab.com/gitlab-com/gitlab-docs/issues/50) for implementing Kramdown in the near future. +Currently GitLab docs use Redcarpet as [markdown](../../user/markdown.md) engine, but there's an [open discussion](https://gitlab.com/gitlab-com/gitlab-docs/issues/50) for implementing Kramdown in the near future. All the docs follow the [documentation style guidelines](styleguide.md). @@ -84,9 +55,18 @@ In order to have a [solid site structure](https://searchengineland.com/seo-benef all docs should be linked. Every new document should be cross-linked to its related documentation, and linked from its topic-related index, when existent. The directories `/workflow/`, `/gitlab-basics/`, `/university/`, and `/articles/` have -been deprecated and the majority their docs have been moved to their correct location +been **deprecated** and the majority their docs have been moved to their correct location in small iterations. Please don't create new docs in these folders. +### Documentation files + +- When you create a new directory, always start with an `index.md` file. +Do not use another file name and **do not** create `README.md` files +- **Do not** use special chars and spaces, or capital letters in file names, +directory names, branch names, and anything that generates a path. +- Max screenshot size: 100KB +- We do not support videos (yet) + ### Location and naming documents The documentation hierarchy can be vastly improved by providing a better layout @@ -116,7 +96,7 @@ The table below shows what kind of documentation goes where. --- -**General rules:** +**General rules & best practices:** 1. The correct naming and location of a new document, is a combination of the relative URL of the document in question and the GitLab Map design @@ -203,7 +183,7 @@ Things to note: documentation, sometimes it might be useful to search a path deeper. - The `*.md` extension is not used when a document is linked to GitLab's built-in help page, that's why we omit it in `git grep`. -- Use the checklist on the documentation MR description template. +- Use the checklist on the "Change documentation location" MR description template. #### Alternative redirection method @@ -514,7 +494,7 @@ Suppose there's a process to go from point A to point B in 5 steps: `(A) 1 > 2 > A **guide** can be understood as a description of certain processes to achieve a particular objective. A guide brings you from A to B describing the characteristics of that process, but not necessarily going over each step. It can mention, for example, steps 2 and 3, but does not necessarily explain how to accomplish them. -- Live example: "[Static sites and GitLab Pages domains (Part 1)](../user/project/pages/getting_started_part_one.md) to [Creating and Tweaking GitLab CI/CD for GitLab Pages (Part 4)](../../user/project/pages/getting_started_part_four.md)" +- Live example: "[Static sites and GitLab Pages domains (Part 1)](../../user/project/pages/getting_started_part_one.md) to [Creating and Tweaking GitLab CI/CD for GitLab Pages (Part 4)](../../user/project/pages/getting_started_part_four.md)" A **tutorial** requires a clear **step-by-step** guidance to achieve a singular objective. It brings you from A to B, describing precisely all the necessary steps involved in that process, showing each of the 5 steps to go from A to B. It does not only describes steps 2 and 3, but also shows you how to accomplish them. diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md new file mode 100644 index 00000000000..1002836096a --- /dev/null +++ b/doc/development/documentation/structure.md @@ -0,0 +1,149 @@ +--- +description: Learn the how to correctly structure GitLab documentation. +--- + +# Documentation structure + +For consistency throughout the documentation, it's important to maintain the same +structure among the docs. + +Before getting started, read through the following docs: + +- [Contributing to GitLab documentation](index.md#contributing-to-docs) +- [Merge requests for GitLab documentation](index.md#merge-requests-for-gitlab-documentation) +- [Branch naming for docs-only changes](index.md#branch-naming) +- [Documentation directory structure](index.md#documentation-directory-structure) +- [Documentation style guidelines](styleguide.md) +- [Documentation workflow](workflow.md) + +## Documentation blurb + +Every document should include the following content in the following sequence: + +- **Feature name**: defines an intuitive name for the feature that clearly +states what it is and is consistent with any relevant UI text. +- **Feature overview** and description: describe what it is, what it does, and in what context it should be used. +- **Use cases**: describes real use case scenarios for that feature. +- **Requirements**: describes what software and/or configuration is required to be able to +use the feature and, if applicable, prerequisite knowledge for being able to follow/implement the tutorial. +For example, familiarity with GitLab CI/CD, an account on a third-party service, dependencies installed, etc. +Link each one to its most relevant resource; i.e., where the reader can go to begin to fullfil that requirement. +(Another doc page, a third party application's site, etc.) +- **Instructions**: clearly describes the steps to use the feature, leaving no gaps. +- **Troubleshooting** guide (recommended but not required): if you know beforehand what issues +one might have when setting it up, or when something is changed, or on upgrading, it's +important to describe those too. Think of things that may go wrong and include them in the +docs. This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. Answering them beforehand only makes your +document better and more approachable. + +For additional details, see the subsections below, as well as the [Documentation template for new docs](#Documentation-template-for-new-docs). + +### Feature overview and use cases + +Every major feature (regardless if present in GitLab Community or Enterprise editions) +should present, at the beginning of the document, two main sections: **overview** and +**use cases**. Every GitLab EE-only feature should also contain these sections. + +**Overview**: as the name suggests, the goal here is to provide an overview of the feature. +Describe what is it, what it does, why it is important/cool/nice-to-have, +what problem it solves, and what you can do with this feature that you couldn't +do before. + +**Use cases**: provide at least two, ideally three, use cases for every major feature. +You should answer this question: what can you do with this feature/change? Use cases +are examples of how this feature or change can be used in real life. + +Examples: +- CE and EE: [Issues](../user/project/issues/index.md#use-cases) +- CE and EE: [Merge Requests](../user/project/merge_requests/index.md#overview) +- EE-only: [Geo](https://docs.gitlab.com/ee/gitlab-geo/README.html#overview) +- EE-only: [Jenkins integration](https://docs.gitlab.com/ee/integration/jenkins.md#overview) + +Note that if you don't have anything to add between the doc title (`<h1>`) and +the header `## Overview`, you can omit the header, but keep the content of the +overview there. + +> **Overview** and **use cases** are required to **every** Enterprise Edition feature, +and for every **major** feature present in Community Edition. + +### Discoverability + +Your new document will be discoverable by the user only if: + +- Crosslinked from the higher-level index (e.g., Issue Boards docs +should be linked from Issues; Prometheus docs should be linked from +Monitoring; CI/CD tutorials should be linked from CI/CD examples). + - When referencing other GitLab products and features, link to their +respective docs; when referencing third-party products or technologies, +link out to their external sites, documentation, and resources. +- The headings are clear. E.g., "App testing" is a bad heading, "Testing +an application with GitLab CI/CD" is much better. Think of something +someone will search for and use these keywords in the headings. + +## Documentation template for new docs + +To start a new document, respect the file tree and file name guidelines, +as well as the style guidelines. Use the following template: + +```md +--- +description: "short document description." # Up to ~200 chars long. They will be displayed in Google Search Snippets. +--- + +# Feature Name **[TIER]** (1) + +> [Introduced](link_to_issue_or_mr) in GitLab Tier X.Y (2). + +A short description for the feature (can be the same used in the frontmatter's +`description`). + +## Overview + +To write the feature overview, you should consider answering the following questions: + +- What is it? +- Who is it for? +- What is the context in which it is used and are there any prerequisites/requirements? +- What can the user do with it? (Be sure to consider multiple audiences, like GitLab admin and developer-user.) +- What are the benefits to using it over any alternatives? + +## Use cases + +Describe one to three use cases for that feature. Give real-life examples. + +## Requirements + +State any requirements, if any, for using the feature and/or following along with the tutorial. + +The only assumption that is redundant and doesn't need to be mentioned is having an account +on GitLab. + +## Instructions + +("Instructions" is not necessarily the name of the heading) + +- Write a step-by-step guide, with no gaps between the steps. +- Start with an h2 (`##`), break complex steps into small steps using +subheadings h3 > h4 > h5 > h6. _Never skip the hierarchy level, such +as h2 > h4_, as it will break the TOC and may affect the breadcrumbs. +- Use short and descriptive headings (up to ~50 chars). You can use one +single heading `## How it works` for the instructions when the feature +is simple and the document is short. +- Be clear, concise, and stick to the goal of the doc: explain how to +use that feature. +- Use inclusive language and avoid jargons, as well as uncommon and +fancy words. The docs should be clear and very easy to understand. +- Write in the 3rd person (use "we", "you", "us", "one", instead of "I" or "me"). +- Always provide internal and external reference links. +- Always link the doc from its higher-level index. + +<!-- ## Troubleshooting + +Add a troubleshooting guide when possible/applicable. --> +``` + +Notes: + +- (1): Apply the [tier badges](styleguide.md#product-badges) accordingly +- (2): Apply the correct format for the [GitLab version introducing the feature](styleguide.md#gitlab-versions-and-tiers) diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index ad49c77aac8..6c60a517b6d 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -10,6 +10,22 @@ GitLab documentation. Check the Check the GitLab handbook for the [writing styles guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines). +## Files + +- [Directory structure](index.md#location-and-naming-documents): place the docs +in the correct location +- [Documentation files](index.md#documentation-files): name the files accordingly +- [Markdown](../../user/markdown.md): use the GitLab Flavored Markdown in the +documentation + +NOTE: **Note:** +**Do not** use capital letters, spaces, or special chars in file names, +branch names, directory names, headings, or in anything that generates a path. + +NOTE: **Note:** +**Do not** create new `README.md` files, name them `index.md` instead. There's +a test that will fail if it spots a new `README.md` file. + ## Text - Split up long lines (wrap text), this makes it much easier to review and edit. Only @@ -61,7 +77,8 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl - Add **only one H1** in each document, by adding `#` at the beginning of it (when using markdown). The `h1` will be the document `<title>`. -- For subheadings, use `##`, `###` and so on +- 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 links shift too, which eventually leads to dead links. If you think it is compelling to add numbers in headings, make sure to at least discuss it with @@ -115,10 +132,7 @@ needs to expand the tab to find the settings you're referring to the `.md` document that you're working on is located. Always prepend their names with the name of the document that they will be included in. For example, if there is a document called `twitter.md`, then a valid image name - could be `twitter_login_screen.png`. [**Exception**: images for - [articles](index.md#technical-articles) should be - put in a directory called `img` underneath `/articles/article_title/img/`, therefore, - there's no need to prepend the document name to their filenames.] + could be `twitter_login_screen.png`. - Images should have a specific, non-generic name that will differentiate them. - Keep all file names in lower case. - Consider using PNG images instead of JPEG. @@ -126,6 +140,8 @@ needs to expand the tab to find the settings you're referring to - 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. +- Max image size: 100KB (gifs included). +- The GitLab docs do not support videos yet. Inside the document: diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md new file mode 100644 index 00000000000..339ec80f889 --- /dev/null +++ b/doc/development/documentation/workflow.md @@ -0,0 +1,186 @@ +--- +description: Learn the process of shipping documentation for GitLab. +--- + +# Documentation process at GitLab + +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. + +- Product Managers (PMs): in the issue for all new and updated features, +PMs include specific documentation requirements that the developer who is +writing or updating the docs must meet, along with feature descriptions +and use cases. They call out any specific areas where collaborating with +a technical writer is recommended, and usually act as the first reviewer +of the docs. +- Developers: author documentation and merge it on time (up to a week after +the feature freeze). +- Technical Writers: review each issue to ensure PM's requirements are complete, +help developers with any questions throughout the process, and act as the final +reviewer of all new and updated docs content before it's merged. + +## Requirements + +Documentation must be delivered whenever: + +- A new feature is shipped +- There are changes to the UI +- A process, workflow, or previously documented feature is changed + +Documentation is not required when a feature is changed on the backend +only and does not directly affect the way that any regular user or +administrator would interact with GitLab. + +NOTE: **Note:** +When refactoring documentation in needed, it should be submitted it in its own MR. +**Do not** join new features' MRs with refactoring existing docs, as they might have +different priorities. + +NOTE: **Note:** +[Smaller MRs are better](https://gitlab.com/gitlab-com/blog-posts/issues/185#note_4401010)! Do not mix subjects, and ship the smallest MR possible. + +### Documentation review process + +The docs shipped by the developer should be reviewed by the PM (for accuracy) and a Technical Writer (for clarity and structure). + +#### Documentation updates that require Technical Writer review + +Every documentation change that meets the criteria below must be reviewed by a Technical Writer +to ensure clarity and discoverability, and avoid redundancy, bad file locations, typos, broken links, etc. +Within the GitLab issue or MR, ping the relevant technical writer for the subject area. If you're not sure who that is, +ping any of them or all of them (`@gl\-docsteam`). + +A Technical Writer must review documentation updates that involve: + +- Docs introducing new features +- Changing documentation location +- Refactoring existing documentation +- Creating new documentation files + +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 a Technical Writer on your issue, MR, +or on Slack in `#docs`. + +#### Skip the PM's review + +When there's a non-significant change to the docs, you can skip the review +of the PM. Add the same labels as you would for a regular doc change and +assign the correct milestone. In these cases, assign a Technical Writer +for approval/merge, or mention `@gl\-docsteam` in case you don't know +which Tech Writer to assign for. + +#### Skip the entire review + +When the MR only contains corrections to the content (typos, grammar, +broken links, etc), it can be merged without the PM's and Tech Writer's review. + +## Documentation structure + +Read through the [documentation structure](structure.md) docs for an overview. + +## Documentation workflow + +To follow a consistent workflow every month, documentation changes +involve the Product Managers, the developer who shipped the feature, +and the Technical Writing team. Each role is described below. + +### 1. Product Manager's role in the documentation process + +The Product Manager (PM) should add to the feature issue: + +- Feature name, overview/description, and use cases, for the [documentation blurb](structure.md#documentation-blurb) +- The documentation requirements for the developer working on the docs + - What new page, new subsection of an existing page, or other update to an existing page/subsection is needed. + - Just one page/section/update or multiple (perhaps there's an end user and admin change needing docs, or we need to update a previously recommended workflow, or we want to link the new feature from various places; consider and mention all ways documentation should be affected + - Suggested title of any page or subsection, if applicable +- Label the issue with `Documentation`, `Deliverable`, `docs:P1`, and assign + the correct milestone + +### 2. Developer's role in the documentation process + +As a developer, or as a community contributor, you should ship the documentation +with the feature, as in GitLab the documentation is part of the product. + +The docs can either be shipped along with the MR introducing the code, or, +alternatively, created from a follow-up issue and MR. + +The docs should be shipped **by the feature freeze date**. Justified +exceptions are accepted, as long as the [following process](#documentation-shipped-late) +and the missed-deliverable due date (the 14th of each month) are both respected. + +#### Documentation shipped in the feature MR + +The developer should add to the feature MR the documentation containing: + +- The [documentation blurb](structure.md#documentation-blurb): copy the +feature name, overview/description, and use cases from the feature issue +- Instructions: write how to use the feature, step by step, with no gaps. +- [Crosslink for discoverability](structure.md#discoverability): link with +internal docs and external resources (if applicable) +- Index: link the new doc or the new heading from the higher-level index +for [discoverability](#discoverability) +- [Screenshots](styleguide.md#images): when necessary, add screenshots for: + - Illustrating a step of the process + - Indicating the location of a navigation menu +- Label the MR with `Documentation`, `Deliverable`, `docs-P1`, and assign +the correct milestone +- Assign the PM for review +- When done, mention the `@gl\-docsteam` in the MR asking for review +- **Due date**: feature freeze date and time + +#### Documentation shipped in a follow-up MR + +If the docs aren't being shipped within the feature MR: + +- Create a new issue mentioning "docs" or "documentation" in the title (use the Documentation issue description template) +- Label the issue with: `Documentation`, `Deliverable`, `docs-P1`, `<product-label>` +(product label == CI/CD, Pages, Prometheus, etc) +- Add the correct milestone +- Create a new MR for shipping the docs changes and follow the same +process [described above](#documentation-shipped-in-the-feature-mr) +- Use the MR description template called "Documentation" +- Add the same labels and milestone as you did for the issue +- Assign the PM for review +- When done, mention the `@gl\-docsteam` in the MR asking for review +- **Due date**: feature freeze date and time + +#### Documentation shipped late + +Shipping late means that you are affecting the whole feature workflow +as well as other teams' priorities (PMs, tech writers, release managers, +release post reviewers), so every effort should be made to avoid this. + +If you did not ship the docs within the feature freeze, proceed as +[described above](#documentation-shipped-in-a-follow-up-mr) and, +besides the regular labels, include the labels `Pick into X.Y` and +`missed-deliverable` in the issue and the MR, and assign them the correct +milestone. + +The **due date** for **merging** `missed-deliverable` MRs is on the +**14th** of each month. + +### 3. Technical Writer's role in the documentation process + +- **Planning** + - Once an issue contains a Documentation label and the current milestone, a +technical writer reviews the Product Manager's documentation requirements + - Once the documentation requirements are approved, the technical writer can +work with the developer to discuss any documentation questions and plans/outlines, as needed. + +- **Review** - A technical writer must review the documentation for: + - Clarity + - Relevance (make sure the content is appropriate given the impact of the feature) + - Location (make sure the doc is in the correct dir and has the correct name) + - Syntax, typos, and broken links + - Improvements to the content + - Accordance to the [docs style guide](styleguide.md) + +<!-- TBA: issue and MR description templates as part of the process --> + +<!-- +## New features vs feature updates + +- TBA: + - Describe the difference between new features and feature updates + - Creating a new doc vs updating an existing doc +--> + |