Documentation process at GitLab
This commit is contained in:
Marcia Ramos
parent
0a666b2cb1
commit
819f6d9bce
8 changed files with 507 additions and 70 deletions
54
.gitlab/issue_templates/Documentation.md
Normal file
54
.gitlab/issue_templates/Documentation.md
Normal file
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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?
|
||||
## Author's checklist
|
||||
|
||||
Read the guidelines:
|
||||
https://docs.gitlab.com/ee/development/documentation/#changing-document-location
|
||||
- [ ] [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_
|
||||
|
||||
- [ ] 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.
|
||||
## 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
|
||||
|
|
|
|||
33
PROCESS.md
33
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
Please read through the [documentation workflow](workflow.md) before getting started.
|
||||
|
||||
## 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.
|
||||
|
||||
**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.
|
||||
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.
|
||||
|
|
|
|||
149
doc/development/documentation/structure.md
Normal file
149
doc/development/documentation/structure.md
Normal file
|
|
@ -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)
|
||||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
186
doc/development/documentation/workflow.md
Normal file
186
doc/development/documentation/workflow.md
Normal file
|
|
@ -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
|
||||
-->
|
||||
|
||||
Loading…
Reference in a new issue