Merge branch 'documentation-development-docs' into 'master'

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

See merge request gitlab-org/gitlab-ce!23951

doc/development/documentation/feature-change-workflow.md

+---
+description: How to add docs for new or enhanced GitLab features.
+---
+
+# 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.
+
+- **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.
+- **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 help, 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,
+and review all new and updated docs content after it's merged (unless a pre-merge
+review request is made).
+
+Beyond this process, any member of the GitLab community can also author 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
+
+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. 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.
+
+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.
+
+## 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 Writing team. Each role is described below.
+
+### 1. Product Manager's role
+
+The Product Manager (PM) should confirm or add the following items in the issue:
+
+- New or updated feature name, overview/description, and use cases, all required per the [Documentation structure and template](structure.md).
+- 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` and `docs:P1` in addition to the `Deliverable` label and correct milestone.
+
+Anyone is welcome to draft the items above in the issue, but a product manager must review and update them whenever the issue is assigned a specific milestone. 
+
+### 2. Developer's role
+
+As a developer, you must ship the documentation with the code of the feature that
+you are creating or updating. The documentation is an essential part of the product.
+
+- New and edited docs should be included in the MR introducing the code, and planned
+in the issue that proposed the feature. However, if the new or changed doc 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 the [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.
+- The docs must be merged with the code **by the feature freeze date**, otherwise
+- the feature cannot be included with the release.<!-- TODO: Policy/process for feature-flagged issues -->
+
+Prior to merge, documentation changes commited by the developer must be reviewed by:
+* the person reviewing the code and merging the MR.
+* optionally: others involved in the work (such as other devs, the PM, or a technical writer), if requested.
+
+After merging, documentation changing are reviewed by:
+* a technical writer (for clarity, structure, grammar, etc).
+* 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.
+
+### 3. Technical Writer's role
+
+**Planning**
+- Once an issue contains a Documentation label and an upcoming milestone, a
+technical writer reviews the listed documentation requirements, which should have
+already been reviewed by the PM. (These are non-blocking reviews; developers should
+not wait to work on docs.)
+- Monitor the documentation needs of issues assigned to the current and next milestone,
+and participate in any needed discussion on docs planning with the dev, PM, and others.
+
+**Review**
+- Techncial writers provide non-blocking reviews of all documentation changes,
+typically after the change is merged. However, if the docs are ready in the MR while
+we are awaiting other work in order to merge, the technical writer's review can commence early.
+- 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.
+  - 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 [Documentation Style Guide](styleguide.md) and [structure/template](structure.md).

doc/development/documentation/improvement-workflow.md

+---
+description: How to improve GitLab's documentation.
+---
+
+# 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 [feature-change documentation workflow](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 admin
+to achieve or improve their DevOps workflows.
+
+## How to update the docs
+
+- Follow the described standards and processes listed on the [GitLab Documentation guidelines](index.md) page,
+including 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/). 
+- 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.
+
+## 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).
+
+## Technical Writer review
+
+The technical writing team reviews changes after they are merged, unless a prior
+review is requested.
+
+## 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.

doc/development/documentation/site_architecture/index.md

@@ -2,11 +2,18 @@
 description: "Learn how GitLab's documentation website is architectured."
 ---
 
-# Docs site architecture
+# Documentation site architecture
 
 Learn how we build and architecture [`gitlab-docs`](https://gitlab.com/gitlab-com/gitlab-docs)
 and deploy it to <https://docs.gitlab.com>.
 
+## Repository
+
+While the source of the documentation content is stored in GitLab's respective product
+repositories, the source that is used to build the documentation site _from that content_
+is located at https://gitlab.com/gitlab-com/gitlab-docs. See the README there for
+detailed information.
+
 ## Assets
 
 To provide an optimized site structure, design, and a search-engine friendly

doc/development/documentation/styleguide.md

 ---
-description: 'Writing styles, markup, formatting, and reusing regular expressions throughout the GitLab Documentation.'
+description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.'
 ---
 
-# Documentation style guidelines
+# Documentation Style Guide
 
 The documentation style guide defines the markup structure used in
 GitLab documentation. Check the
 [documentation guidelines](index.md) for general development instructions.
 
-Check the GitLab handbook for the [writing styles guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines).
+See the GitLab handbook for the [writing style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines).
 
-For help adhering to the guidelines, see [linting](index.md#linting).
+For programmatic help adhering to the guidelines, see [linting](index.md#linting).
 
 ## Files
 
@@ -40,13 +40,36 @@ Use Kramdown markup wisely: do not overuse its specific markup (e.g., `{:.class}
 
 ## Content
 
-- Make sure that the documentation is added in the correct
-  [directory](index.md#documentation-directory-structure), linked from its
-  higher-level index, and linked from other related pages.
+These guidelines help toward the goal of having every user's search of documentation
+yield a useful result, and ensuring content is helpful and easy to consume.
+
+- What to include:
+  - Any and all helpful information, processes, and tips for implementing,
+using, and troubleshooting GitLab features. [The documentation is the single source of truth](https://about.gitlab.com/handbook/documentation/#documentation-as-single-source-of-truth-ssot)
+for this information.
+  - 'Risky' or niche problem-solving steps. There is no reason to withhold these or
+store them elsewhere; simply include them along with the rest of the docs including all necessary
+detail, such as specific warnings and caveats about potential ramifications.
+  - Any content types/sources, if relevant to users or admins. You can freely
+include presentations, videos, etc.; no matter who it was originally written for,
+if it is helpful to any of our audiences, we can include it. If an outside source
+that's under copyright, rephrase, or summarize and link out; do not copy and paste.
+  - All applicable subsections as described on the [structure and template](structure.md) page,
+with files organized in the [correct directory](index.md#documentation-directory-structure).
+- To ensure discoverability, link to each doc from its higher-level index page and other related pages.
+- 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.
 - Do not duplicate information.
-- Be brief and clear.
-- Unless there's a logical reason not to, structure the document in alphabetical order
-(headings, tables, and lists).
+- Structure content in alphabetical order in tables, lists, etc., unless there is
+a logical reason not to (for example, when mirroring the UI or an ordered sequence). 
+
+## Language
+
+- 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").
+- Be clear, concise, and stick to the goal of the doc.
 - Write in US English.
 - Capitalize "G" and "L" in GitLab.
 - Use title case when referring to [features](https://about.gitlab.com/features/) or

doc/development/documentation/workflow.md

 ---
-description: Learn the process of shipping documentation for GitLab.
+description: Learn the processes for contributing to GitLab's documentation.
 ---
 
-# Documentation process at GitLab
+# Documentation workflows 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.
+Documentation workflows at GitLab differ depending on the reason for the change. The two types of documentation changes are:
 
-- 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, it should be submitted 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
--->
+- [Feature-change documentation workflow](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.