Updates per reviews; split workflow.md into 2 pages
Split workflow.md into a new feature workflow page vs other improvement workflow page because the original page was too long and using 4 heading levels. Left it in place as an index so we have a single workflow landing page.
This commit is contained in:
Mike Lewis
parent
089233e877
commit
cf414a0b0b
|
|
@ -0,0 +1,173 @@
|
|||
---
|
||||
description: How to add docs for new or enhanced GitLab features.
|
||||
---
|
||||
|
||||
# Feature-change documentation updates
|
||||
|
||||
At GitLab, before each release, 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.
|
||||
|
||||
Documentation pages should follow the [structure](structure.md) guidelines.
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Feature 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)
|
||||
<!-- TODO: Clarify differences for completely new features vs. feature enhancemeents. May belong in structure doc. -->
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
---
|
||||
description: How to improve GitLab's documentation.
|
||||
---
|
||||
|
||||
# Other documentation updates
|
||||
|
||||
Anyone can contribute a merge request or create an issue for GitLab's documentation.
|
||||
|
||||
This page covers the process for general contributions to GitLab's docs (other than those which arise from release-related feature updates) can be found on the documentation guidelines page under [other documentation contributions](index.md#other-documentation-contributions).
|
||||
|
||||
## Role of Support in GitLab Documentation
|
||||
|
||||
GitLab support engineers are key contributors to GitLab docs. They should regularly update docs when handling support cases, where a doc update would enable users to accomplish tasks successfully on their own in the future, preventing problems and the need to contact Support.
|
||||
|
||||
Support and others should use a docs-first approach; rather than directly responding to a customer with a solution, where possible/applicable, first produce an MR for a new or updated doc and then link it in the customer communication / forum reply. If the MR can get merged immediately, even better—just link to the live doc instead.
|
||||
|
||||
Generally, support engineers can contribute to docs in the same way as other improvements are made, but this section contains additional Support-specific tips.
|
||||
|
||||
### Content: what belongs in the docs
|
||||
|
||||
In docs, we share any and all helpful info/processes/tips with customers, but warn them in specific terms about the potential ramifications of any mentioned actions. There is no reason to withhold 'risky' steps and store them in another location; simply include them along with the rest of the docs, with all necessary detail including specific warnings and caveats.
|
||||
|
||||
A `Troubleshooting` section in doc pages is part of the default [template](structure.md) for a new page, and can freely be added to any page.
|
||||
|
||||
These guidelines help toward the goal of having every user's search of documentation yield a useful result.
|
||||
|
||||
### Who can merge
|
||||
|
||||
Who can and should merge depends on the type of update.
|
||||
|
||||
- **If a simple troubleshooting item, minor correction, or other added note/caveat**, and if the content is known by the author to be accurate or has been reviewed by SME, it can be merged by anyone with master permissions (e.g. a Support Manager). However, requests for technical writer review or assistance are always welcome.
|
||||
|
||||
- **If creating/deleting/moving a page or page subsection, or other larger doc updates, including more extensive troubleshooting steps**, we require a technical writer review. However, you can always link a user to your MR before it is merged.
|
||||
|
||||
### 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.
|
||||
<!-- TODO: Update and document issue and MR description templates as part of the process. -->
|
||||
|
|
@ -4,7 +4,7 @@ description: Learn how to contribute to GitLab Documentation.
|
|||
|
||||
# GitLab Documentation guidelines
|
||||
|
||||
GitLab's documentation is intended as the single source of truth (SSOT) for information about how to configure, use, and troubleshoot GitLab.
|
||||
GitLab's documentation is intended as the single source of truth (SSOT) for information about how to configure, use, and troubleshoot GitLab. The documentation contains use cases and usage instructions covering every GitLab feature, organized by product area and subject. This includes topics and workflows that span multiple GitLab features, as well as the use of GitLab with other applications.
|
||||
|
||||
Documentation for GitLab Community Edition (CE) and Enterprise Edition (EE), along with GitLab Runner and Omnibus, is published to [docs.gitlab.com](https://docs.gitlab.com). The documentation for CE and EE is also published within the application at `/help` on the domain of the GitLab instance.
|
||||
|
||||
|
|
@ -21,21 +21,15 @@ The source of the documentation is maintained in the following repository locati
|
|||
|
||||
Documentation issues and merge requests are part of their respective repositories and all have the label `Documentation`.
|
||||
|
||||
The GitLab Documentation contains the following types of pages:
|
||||
|
||||
- **General documentation**: Coverage of every GitLab feature, written by the [developers who created or extended the feature](#contributing-to-docs). This should be submitted in the same merge request containing code. Feature proposals (by GitLab contributors) should also be accompanied by their respective documentation, which should be reviewed and improved by GitLab PMs and technical writers.
|
||||
- **[Technical articles](#technical-articles)**: written by any [GitLab Team](https://about.gitlab.com/team/) member, GitLab contributors, or [Community Writers](https://about.gitlab.com/handbook/product/technical-writing/community-writers/).
|
||||
- **Index pages per topic**: initially prepared by the Technical Writing Team, and kept up-to-date by developers and PMs in the same merge request containing code. These offer links and summaries of all resources for that topic in a single page: user and admin documentation, articles, and third-party docs.
|
||||
|
||||
## Contributing to docs
|
||||
|
||||
Contributions to GitLab docs are welcome from the entire GitLab community.
|
||||
[Contributions to GitLab docs](workflow.md) are welcome from the entire GitLab community.
|
||||
|
||||
To ensure that GitLab docs keep up with changes to the product, special processes and responsibilities are in place concerning all feature changes—i.e. development work that impacts the appearance, usage, or administration of a feature .
|
||||
To ensure that GitLab docs keep up with changes to the product, special processes and responsibilities are in place concerning all [feature changes](feature-change-workflow.md)—i.e. development work that impacts the appearance, usage, or administration of a feature .
|
||||
|
||||
Meanwhile, anyone can contribute to documentation improvements that are not associated with a feature change.
|
||||
Meanwhile, anyone can contribute to [documentation improvements](improvement-workflow.md) that are not associated with a feature change.
|
||||
|
||||
For additional specifics that pertain to support engineers, see [Role of Support in GitLab Documentation](workflow.md#role-of-support-in-gitlab-documentation) in our Workflow doc.
|
||||
For additional specifics that pertain to support engineers, see [Role of Support in GitLab Documentation](improvement-workflow.md#role-of-support-in-gitlab-documentation) in our Improvement Workflow doc.
|
||||
|
||||
### Feature changes
|
||||
|
||||
|
|
@ -51,7 +45,7 @@ When your content is ready for review, request a review from the applicable writ
|
|||
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.
|
||||
|
||||
For more detail on the steps to follow for developers, product managers, and technical writers in this process, see the [documentation workflow](workflow.md) page.
|
||||
For more detail on the steps to follow for developers, product managers, and technical writers in this process, see the [feature-change workflow](feature-change-workflow.md) page.
|
||||
|
||||
### Other documentation contributions
|
||||
|
||||
|
|
@ -59,7 +53,7 @@ If you find content that is missing, incorrect, or could use improvement, you ar
|
|||
|
||||
If the doc exists in both the CE and EE repositories, create the issue or merge request in CE. If the doc or feature exists only in the EE repository, create the issue or merge request in EE.
|
||||
|
||||
If you have questions before or while writing documentation, ask a GitLab technical writer. The technical writer assigned to all features' DevOps stages is displayed automatically in a reply from DangerBot on any merge request that contains changes to doc files.
|
||||
If you have questions before or while writing documentation, ask a GitLab technical writer. The technical writer assigned to all features' DevOps stages is listed on the [Product Categories page](https://about.gitlab.com/handbook/product/categories/#devops-stage) and also displayed in an automatic reply from DangerBot on any merge request that contains changes to doc files.
|
||||
|
||||
When your content is ready for review, request a review from the applicable writer by mentioning them in a comment.
|
||||
|
||||
|
|
@ -92,7 +86,7 @@ all docs should be linked. Every new document should be cross-linked to its rela
|
|||
|
||||
The directories `/workflow/`, `/gitlab-basics/`, `/university/`, and `/articles/` have
|
||||
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.
|
||||
in small iterations. Please do not create new docs in these folders. Organize docs by product area and subject, not type.
|
||||
|
||||
### Documentation files
|
||||
|
||||
|
|
|
|||
|
|
@ -1,221 +1,10 @@
|
|||
---
|
||||
description: Learn the process of shipping documentation for GitLab.
|
||||
description: Learn the processes for contributing to GitLab's documentation.
|
||||
---
|
||||
|
||||
# Documentation workflows at GitLab
|
||||
|
||||
Documentation workflows at GitLab differ depending on whether documentation is
|
||||
being updated due to a feature change (as part of the release process) or is being improved for other reasons, such as a doc revamp or correction.
|
||||
Documentation workflows at GitLab differ depending on the reason for the change. The two types of documentation changes are:
|
||||
|
||||
## Feature change updates
|
||||
|
||||
At GitLab, before each release, 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.
|
||||
|
||||
Documentation pages should follow the [structure](structure.md) guidelines.
|
||||
|
||||
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.
|
||||
|
||||
### 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.
|
||||
|
||||
### Feature 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)
|
||||
|
||||
## Other documentation updates
|
||||
|
||||
Anyone can contribute a merge request or create an issue for documentation.
|
||||
|
||||
The process for genearl contributions to docs (other than those which arise from release-related feature updates) can be found on the documentation guidelines page under [other documentation contributions](index.md#other-documentation-contributions).
|
||||
|
||||
## Role of Support in GitLab Documentation
|
||||
|
||||
GitLab support engineers are key contributors to GitLab docs. They should regularly update docs when handling support cases, where a doc update would enable users to accomplish tasks successfully on their own in the future, preventing problems and the need to contact Support.
|
||||
|
||||
Support and others should use a docs-first approach; rather than directly responding to a customer with a solution, where possible/applicable, first produce an MR for a new or updated doc and then link it in the customer communication / forum reply. If the MR can get merged immediately, even better—just link to the live doc instead.
|
||||
|
||||
Generally, support engineers can contribute to docs in the [same way as other non-feature-enhancement docs are contributed](index.md#, but this section contains additional Support-specific tips.
|
||||
|
||||
### Content: what belongs in the docs
|
||||
|
||||
In docs, we share any and all helpful info/processes/tips with customers, but warn them in specific terms about the potential ramifications of any mentioned actions. There is no reason to withhold 'risky' steps and store them in another location; simply include them along with the rest of the docs, with all necessary detail including specific warnings and caveats.
|
||||
|
||||
A `Troubleshooting` section in doc pages is part of the default [template](structure.md) for a new page, and can freely be added to any page.
|
||||
|
||||
These guidelines help toward the goal of having every user's search of documentation yield a useful result.
|
||||
|
||||
### Who can merge
|
||||
|
||||
Who can and should merge depends on the type of update.
|
||||
|
||||
- **If a simple troubleshooting item, minor correction, or other added note/caveat**, if known by the author to be accurate or has been reviewed by SME, can be merged by anyone with master permissions (e.g. Support Manager). However, requests for technical writer review or assistance are always welcome.
|
||||
|
||||
- **If creating/deleting/moving a page or page subsection, or other larger doc updates, including more extensive troubleshooting steps**, we require a technical writer review. However, you can always link a user to your MR, for reference.
|
||||
|
||||
### 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.
|
||||
|
||||
<!-- 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 Updates](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, along with the product manager and technical writer who are listed for the feature's [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). Typically, the necessary changes to documentation files are included as part of the new feature's merge request.
|
||||
- [Improvements](improvement-workflow.md) - The documentation is being created or updated to improve accuracy, completeness, ease of use, or any other improvement not related to a feature change. Anyone (and everyone) can contribute a merge request for this type of update.
|
||||
|
|
|
|||
Loading…
Reference in New Issue