Skip to content

G
gitlab-ce
Commit 0df7adef authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files
Options

Merge branch 'docs/refine-markdown-proselint-config' into 'master' 

Add refined sample linting configuration

See merge request gitlab-org/gitlab-ce!22827
parents abedad6a 8c9da81c
Show whitespace changes
Inline Side-by-side
Showing with 114 additions and 98 deletions
doc/development/documentation/index.md
View file @ 0df7adef
...@@ -4,9 +4,9 @@ description: Learn how to contribute to GitLab Documentation. ...@@ -4,9 +4,9 @@ description: Learn how to contribute to GitLab Documentation.
# GitLab Documentation guidelines # GitLab Documentation guidelines
- **General Documentation**: written by the [developers responsible by creating features](#contributing-to-docs). Should be submitted in the same merge request containing code. Feature proposals (by GitLab contributors) should also be accompanied by its respective documentation. They can be later improved by PMs and Technical Writers. - **General Documentation**: written by the [developers responsible by creating features](#contributing-to-docs). Should be submitted in the same merge request containing code. Feature proposals (by GitLab contributors) should also be accompanied by its respective documentation. They can be later improved by 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/). - **[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/).
- **Indexes 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. They gather all resources for that topic in a single page (user and admin documentation, articles, and third-party docs). - **Indexes 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. They gather all resources for that topic in a single page (user and admin documentation, articles, and third-party docs).
## Contributing to docs ## Contributing to docs
...@@ -41,7 +41,7 @@ how to structure GitLab docs. ...@@ -41,7 +41,7 @@ how to structure GitLab docs.
## Markdown and styles ## 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 [Kramdown](https://gitlab.com/gitlab-com/gitlab-docs/issues/50) as the [markdown](../../user/markdown.md) engine.
All the docs follow the [documentation style guidelines](styleguide.md). See [Linting](#linting) for help to follow the guidelines. All the docs follow the [documentation style guidelines](styleguide.md). See [Linting](#linting) for help to follow the guidelines.
...@@ -61,11 +61,11 @@ in small iterations. Please don't create new docs in these folders. ...@@ -61,11 +61,11 @@ in small iterations. Please don't create new docs in these folders.
### Documentation files ### Documentation files
- When you create a new directory, always start with an `index.md` file. - 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 another file name and **do not** create `README.md` files.
- **Do not** use special chars and spaces, or capital letters in file names, - **Do not** use special chars and spaces, or capital letters in file names,
directory names, branch names, and anything that generates a path. directory names, branch names, and anything that generates a path.
- Max screenshot size: 100KB - Max screenshot size: 100KB.
- We do not support videos (yet) - We do not support videos (yet).
### Location and naming documents ### Location and naming documents
...@@ -84,13 +84,13 @@ and cross-link between any related content. ...@@ -84,13 +84,13 @@ and cross-link between any related content.
The table below shows what kind of documentation goes where. The table below shows what kind of documentation goes where.
| Directory | What belongs here | | Directory | What belongs here |
| --------- | -------------- | |:----------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `doc/user/` | User related documentation. Anything that can be done within the GitLab UI goes here including `/admin`. | | `doc/user/` | User related documentation. Anything that can be done within the GitLab UI goes here including `/admin`. |
| `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. The admin settings that can be accessed via GitLab's interface go under `doc/user/admin_area/`. | | `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. The admin settings that can be accessed via GitLab's interface go under `doc/user/admin_area/`. |
| `doc/api/` | API related documentation. | | `doc/api/` | API related documentation. |
| `doc/development/` | Documentation related to the development of GitLab. Any styleguides should go here. | | `doc/development/` | Documentation related to the development of GitLab. Any styleguides should go here. |
| `doc/legal/` | Legal documents about contributing to GitLab. | | `doc/legal/` | Legal documents about contributing to GitLab. |
| `doc/install/`| Probably the most visited directory, since `installation.md` is there. Ideally this should go under `doc/administration/`, but it's best to leave it as-is in order to avoid confusion (still debated though). | | `doc/install/` | Probably the most visited directory, since `installation.md` is there. Ideally this should go under `doc/administration/`, but it's best to leave it as-is in order to avoid confusion (still debated though). |
| `doc/update/` | Same with `doc/install/`. Should be under `administration/`, but this is a well known location, better leave as-is, at least for now. | | `doc/update/` | Same with `doc/install/`. Should be under `administration/`, but this is a well known location, better leave as-is, at least for now. |
| `doc/topics/` | Indexes per Topic (`doc/topics/topic-name/index.md`): all resources for that topic (user and admin documentation, articles, and third-party docs) | | `doc/topics/` | Indexes per Topic (`doc/topics/topic-name/index.md`): all resources for that topic (user and admin documentation, articles, and third-party docs) |
...@@ -134,13 +134,13 @@ merge request. ...@@ -134,13 +134,13 @@ merge request.
Changing a document's location is not to be taken lightly. Remember that the Changing a document's location is not to be taken lightly. Remember that the
documentation is available to all installations under `help/` and not only to documentation is available to all installations under `help/` and not only to
GitLab.com or http://docs.gitlab.com. Make sure this is discussed with the GitLab.com or <http://docs.gitlab.com>. Make sure this is discussed with the
Documentation team beforehand. Documentation team beforehand.
If you indeed need to change a document's location, do NOT remove the old If you indeed need to change a document's location, do NOT remove the old
document, but rather replace all of its contents with a new line: document, but rather replace all of its contents with a new line:
``` ```md
This document was moved to [another location](path/to/new_doc.md). This document was moved to [another location](path/to/new_doc.md).
``` ```
...@@ -154,7 +154,7 @@ For example, if you were to move `doc/workflow/lfs/lfs_administration.md` to ...@@ -154,7 +154,7 @@ For example, if you were to move `doc/workflow/lfs/lfs_administration.md` to
1. Copy `doc/workflow/lfs/lfs_administration.md` to `doc/administration/lfs.md` 1. Copy `doc/workflow/lfs/lfs_administration.md` to `doc/administration/lfs.md`
1. Replace the contents of `doc/workflow/lfs/lfs_administration.md` with: 1. Replace the contents of `doc/workflow/lfs/lfs_administration.md` with:
``` ```md
This document was moved to [another location](../../administration/lfs.md). This document was moved to [another location](../../administration/lfs.md).
``` ```
...@@ -162,7 +162,7 @@ For example, if you were to move `doc/workflow/lfs/lfs_administration.md` to ...@@ -162,7 +162,7 @@ For example, if you were to move `doc/workflow/lfs/lfs_administration.md` to
A quick way to find them is to use `git grep`. First go to the root directory A quick way to find them is to use `git grep`. First go to the root directory
where you cloned the `gitlab-ce` repository and then do: where you cloned the `gitlab-ce` repository and then do:
``` ```sh
git grep -n "workflow/lfs/lfs_administration" git grep -n "workflow/lfs/lfs_administration"
git grep -n "lfs/lfs_administration" git grep -n "lfs/lfs_administration"
``` ```
...@@ -226,17 +226,16 @@ even if it's `index.html` or `README.html`. ...@@ -226,17 +226,16 @@ even if it's `index.html` or `README.html`.
## Linting ## Linting
To help adhere to the [documentation style guidelines](styleguide.md), and to improve the content To help adhere to the [documentation style guidelines](styleguide.md), and to improve the content
added to documentation, consider locally installing and running documentation linters. This will added to documentation, consider locally installing and running documentation linters. This will
help you catch common issues before raising merge requests for review of documentation. help you catch common issues before raising merge requests for review of documentation.
The following are some suggested linters you can install locally and sample configuration: The following are some suggested linters you can install locally and sample configuration:
- `proselint` - [`proselint`](#proselint)
- `markdownlint` - [`markdownlint`](#markdownlint)
NOTE: **Note:** NOTE: **Note:**
This list does not limit what other linters you can add to your local documentation writing This list does not limit what other linters you can add to your local documentation writing toolchain.
toolchain.
### `proselint` ### `proselint`
...@@ -262,19 +261,20 @@ proselint **/*.md ...@@ -262,19 +261,20 @@ proselint **/*.md
#### Sample `proselint` configuration #### Sample `proselint` configuration
All of the checks are good to use. However, excluding the `typography.symbols` checks might reduce All of the checks are good to use. However, excluding the `typography.symbols` and `misc.phrasal_adjectives` checks will reduce
noise. The following sample `proselint` configuration disables the `typography.symbols` checks: noise. The following sample `proselint` configuration disables these checks:
```json ```json
{ {
"checks": { "checks": {
"typography.symbols": false "typography.symbols": false,
"misc.phrasal_adjectives": false
} }
} }
``` ```
A file with `proselint` configuration must be placed in a A file with `proselint` configuration must be placed in a
[valid location](https://github.com/amperser/proselint#checks). For example, `~/.config/proselint/config`. [valid location](https://github.com/amperser/proselint#checks). For example, `~/.config/proselint/config`.
### `markdownlint` ### `markdownlint`
...@@ -306,6 +306,7 @@ The following sample `markdownlint` configuration modifies the available default ...@@ -306,6 +306,7 @@ The following sample `markdownlint` configuration modifies the available default
- Adhere to the [style guidelines](styleguide.md). - Adhere to the [style guidelines](styleguide.md).
- Apply conventions found in the GitLab documentation. - Apply conventions found in the GitLab documentation.
- Allow the flexibility of using some inline HTML.
```json ```json
{ {
...@@ -316,14 +317,31 @@ The following sample `markdownlint` configuration modifies the available default ...@@ -316,14 +317,31 @@ The following sample `markdownlint` configuration modifies the available default
"no-trailing-punctuation": false, "no-trailing-punctuation": false,
"ol-prefix": { "style": "one" }, "ol-prefix": { "style": "one" },
"blanks-around-fences": false, "blanks-around-fences": false,
"no-inline-html": {
"allowed_elements": [
"table",
"tbody",
"tr",
"td",
"ul",
"ol",
"li",
"br",
"img",
"a",
"strong",
"i",
"div"
]
},
"hr-style": { "style": "---" }, "hr-style": { "style": "---" },
"fenced-code-language": false "fenced-code-language": false
} }
``` ```
For [`markdownlint`](https://github.com/DavidAnson/markdownlint/), this configuration must be For [`markdownlint`](https://github.com/DavidAnson/markdownlint/), this configuration must be
placed in a [valid location](https://github.com/igorshubovych/markdownlint-cli#configuration). For placed in a [valid location](https://github.com/igorshubovych/markdownlint-cli#configuration). For
example, `~/.markdownlintrc`. example, `~/.markdownlintrc`.
## Testing ## Testing
...@@ -351,7 +369,7 @@ the CI process by following some branch naming conventions. You have three ...@@ -351,7 +369,7 @@ the CI process by following some branch naming conventions. You have three
choices: choices:
| Branch name | Valid example | | Branch name | Valid example |
| ----------- | ------------- | |:----------------------|:-----------------------------|
| Starting with `docs/` | `docs/update-api-issues` | | Starting with `docs/` | `docs/update-api-issues` |
| Starting with `docs-` | `docs-update-api-issues` | | Starting with `docs-` | `docs-update-api-issues` |
| Ending in `-docs` | `123-update-api-issues-docs` | | Ending in `-docs` | `123-update-api-issues-docs` |
...@@ -400,15 +418,15 @@ Follow this [method for cherry-picking from CE to EE](../automatic_ce_ee_merge.m ...@@ -400,15 +418,15 @@ Follow this [method for cherry-picking from CE to EE](../automatic_ce_ee_merge.m
- Create the EE-equivalent branch ending with `-ee`, e.g., - Create the EE-equivalent branch ending with `-ee`, e.g.,
`git checkout -b docs-example-ee` `git checkout -b docs-example-ee`
- Once all the jobs are passing in CE and EE, and you've addressed the - Once all the jobs are passing in CE and EE, and you've addressed the
feedback from your own team, assign the CE MR to a technical writer for review feedback from your own team, assign the CE MR to a technical writer for review
- When both MRs are ready, the EE merge request will be merged first, and the - When both MRs are ready, the EE merge request will be merged first, and the
CE-equivalent will be merged next. CE-equivalent will be merged next.
- Note that the review will occur only in the CE MR, as the EE MR - Note that the review will occur only in the CE MR, as the EE MR
contains the same commits as the CE MR. contains the same commits as the CE MR.
- If you have a few more changes that apply to the EE-version only, you can submit - If you have a few more changes that apply to the EE-version only, you can submit
a couple more commits to the EE branch, but ask the reviewer to review the EE merge request a couple more commits to the EE branch, but ask the reviewer to review the EE merge request
additionally to the CE MR. If there are many EE-only changes though, start a new MR additionally to the CE MR. If there are many EE-only changes though, start a new MR
to EE only. to EE only.
## Previewing the changes live ## Previewing the changes live
...@@ -418,9 +436,9 @@ To preview your changes to documentation locally, follow this ...@@ -418,9 +436,9 @@ To preview your changes to documentation locally, follow this
The live preview is currently enabled for the following projects: The live preview is currently enabled for the following projects:
- https://gitlab.com/gitlab-org/gitlab-ce - <https://gitlab.com/gitlab-org/gitlab-ce>
- https://gitlab.com/gitlab-org/gitlab-ee - <https://gitlab.com/gitlab-org/gitlab-ee>
- https://gitlab.com/gitlab-org/gitlab-runner - <https://gitlab.com/gitlab-org/gitlab-runner>
If your branch contains only documentation changes, you can use If your branch contains only documentation changes, you can use
[special branch names](#branch-naming) to avoid long running pipelines. [special branch names](#branch-naming) to avoid long running pipelines.
...@@ -516,8 +534,8 @@ Every GitLab instance includes the documentation, which is available from `/help ...@@ -516,8 +534,8 @@ Every GitLab instance includes the documentation, which is available from `/help
The documentation available online on docs.gitlab.com is continuously The documentation available online on docs.gitlab.com is continuously
deployed every hour from the `master` branch of CE, EE, Omnibus, and Runner. Therefore, deployed every hour from the `master` branch of CE, EE, Omnibus, and Runner. Therefore,
once a merge request gets merged, it will be available online on the same day, once a merge request gets merged, it will be available online on the same day.
but they will be shipped (and available on `/help`) within the milestone assigned However, they will be shipped (and available on `/help`) within the milestone assigned
to the MR. to the MR.
For instance, let's say your merge request has a milestone set to 11.3, which For instance, let's say your merge request has a milestone set to 11.3, which
...@@ -614,7 +632,7 @@ They should be placed in a new directory named `/article-title/index.md` under a ...@@ -614,7 +632,7 @@ They should be placed in a new directory named `/article-title/index.md` under a
- **User guides**: technical content to guide regular users from point A to point B - **User guides**: technical content to guide regular users from point A to point B
- **Admin guides**: technical content to guide administrators of GitLab instances from point A to point B - **Admin guides**: technical content to guide administrators of GitLab instances from point A to point B
- **Technical Overviews**: technical content describing features, solutions, and third-party integrations - **Technical Overviews**: technical content describing features, solutions, and third-party integrations
- **Tutorials**: technical content provided step-by-step on how to do things, or how to reach very specific objectives - **Tutorials**: technical content provided step-by-step on how to do things, or how to reach specific objectives
#### Understanding guides, tutorials, and technical overviews #### Understanding guides, tutorials, and technical overviews
...@@ -646,7 +664,6 @@ with the following information: ...@@ -646,7 +664,6 @@ with the following information:
For example: For example:
```yaml ```yaml
--- ---
author: John Doe author: John Doe
......
doc/development/documentation/styleguide.md
View file @ 0df7adef
...@@ -15,10 +15,10 @@ For help adhering to the guidelines, see [Linting](index.md#linting). ...@@ -15,10 +15,10 @@ For help adhering to the guidelines, see [Linting](index.md#linting).
## Files ## Files
- [Directory structure](index.md#location-and-naming-documents): place the docs - [Directory structure](index.md#location-and-naming-documents): place the docs
in the correct location. in the correct location.
- [Documentation files](index.md#documentation-files): name the files accordingly. - [Documentation files](index.md#documentation-files): name the files accordingly.
- [Markdown](../../user/markdown.md): use the GitLab Flavored Markdown in the - [Markdown](../../user/markdown.md): use the GitLab Flavored Markdown in the
documentation. documentation.
NOTE: **Note:** NOTE: **Note:**
**Do not** use capital letters, spaces, or special chars in file names, **Do not** use capital letters, spaces, or special chars in file names,
...@@ -45,10 +45,10 @@ a test that will fail if it spots a new `README.md` file. ...@@ -45,10 +45,10 @@ a test that will fail if it spots a new `README.md` file.
- Capitalize "G" and "L" in GitLab. - Capitalize "G" and "L" in GitLab.
- Use sentence case for titles, headings, labels, menu items, and buttons. - Use sentence case for titles, headings, labels, menu items, and buttons.
- Use title case when referring to [features](https://about.gitlab.com/features/) or - Use title case when referring to [features](https://about.gitlab.com/features/) or
[products](https://about.gitlab.com/pricing/) (e.g., GitLab Runner, Geo, [products](https://about.gitlab.com/pricing/) (e.g., GitLab Runner, Geo,
Issue Boards, GitLab Core, Git, Prometheus, Kubernetes, etc), and methods or methodologies Issue Boards, GitLab Core, Git, Prometheus, Kubernetes, etc), and methods or methodologies
(e.g., Continuous Integration, Continuous Deployment, Scrum, Agile, etc). Note that (e.g., Continuous Integration, Continuous Deployment, Scrum, Agile, etc). Note that
some features are also objects (e.g. "Merge Requests" and "merge requests"). some features are also objects (e.g. "Merge Requests" and "merge requests").
## Formatting ## Formatting
...@@ -130,9 +130,9 @@ To indicate the steps of navigation through the UI: ...@@ -130,9 +130,9 @@ To indicate the steps of navigation through the UI:
- Use the exact word as shown in the UI, including any capital letters as-is. - Use the exact word as shown in the UI, including any capital letters as-is.
- Use bold text for navigation items and the char `>` as separator - Use bold text for navigation items and the char `>` as separator
(e.g., `Navigate to your project's **Settings > CI/CD**` ). (e.g., `Navigate to your project's **Settings > CI/CD**` ).
- If there are any expandable menus, make sure to mention that the user - If there are any expandable menus, make sure to mention that the user
needs to expand the tab to find the settings you're referring to. needs to expand the tab to find the settings you're referring to.
## Images ## Images
...@@ -147,7 +147,7 @@ needs to expand the tab to find the settings you're referring to. ...@@ -147,7 +147,7 @@ needs to expand the tab to find the settings you're referring to.
- Compress all images with <https://tinypng.com/> or similar tool. - Compress all images with <https://tinypng.com/> or similar tool.
- Compress gifs with <https://ezgif.com/optimize> or similar tool. - Compress gifs with <https://ezgif.com/optimize> or similar tool.
- Images should be used (only when necessary) to _illustrate_ the description - Images should be used (only when necessary) to _illustrate_ the description
of a process, not to _replace_ it. of a process, not to _replace_ it.
- Max image size: 100KB (gifs included). - Max image size: 100KB (gifs included).
- The GitLab docs do not support videos yet. - The GitLab docs do not support videos yet.
...@@ -296,7 +296,7 @@ keyword "only": ...@@ -296,7 +296,7 @@ keyword "only":
- For GitLab Core: `**[CORE ONLY]**`. - For GitLab Core: `**[CORE ONLY]**`.
The tier should be ideally added to headers, so that the full badge will be displayed. The tier should be ideally added to headers, so that the full badge will be displayed.
But it can be also mentioned from paragraphs, list items, and table cells. For these cases, However, it can be also mentioned from paragraphs, list items, and table cells. For these cases,
the tier mention will be represented by an orange question mark. the tier mention will be represented by an orange question mark.
E.g., `**[STARTER]**` renders **[STARTER]**, `**[STARTER ONLY]**` renders **[STARTER ONLY]**. E.g., `**[STARTER]**` renders **[STARTER]**, `**[STARTER ONLY]**` renders **[STARTER ONLY]**.
...@@ -317,7 +317,7 @@ avoid duplication, link to the special document that can be found in ...@@ -317,7 +317,7 @@ avoid duplication, link to the special document that can be found in
[`doc/administration/restart_gitlab.md`][doc-restart]. Usually the text will [`doc/administration/restart_gitlab.md`][doc-restart]. Usually the text will
read like: read like:
``` ```md
Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md) Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md)
for the changes to take effect. for the changes to take effect.
``` ```
...@@ -404,7 +404,7 @@ low. ...@@ -404,7 +404,7 @@ low.
You can use the following fake tokens as examples. You can use the following fake tokens as examples.
| **Token type** | **Token value** | | **Token type** | **Token value** |
| --------------------- | --------------------------------- | |:----------------------|:-------------------------------------------------------------------|
| Private user token | `9koXpg98eAheJpvBs5tK` | | Private user token | `9koXpg98eAheJpvBs5tK` |
| Personal access token | `n671WNGecHugsdEDPsyo` | | Personal access token | `n671WNGecHugsdEDPsyo` |
| Application ID | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` | | Application ID | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` |
...@@ -438,15 +438,15 @@ on this document. Further explanation is given below. ...@@ -438,15 +438,15 @@ on this document. Further explanation is given below.
Use the following table headers to describe the methods. Attributes should Use the following table headers to describe the methods. Attributes should
always be in code blocks using backticks (``` ` ```). always be in code blocks using backticks (``` ` ```).
``` ```md
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |:----------|:-----|:---------|:------------|
``` ```
Rendered example: Rendered example:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |:----------|:-------|:---------|:--------------------|
| `user` | string | yes | The GitLab username | | `user` | string | yes | The GitLab username |
#### cURL commands #### cURL commands
...@@ -460,7 +460,7 @@ Rendered example: ...@@ -460,7 +460,7 @@ Rendered example:
username and password. username and password.
| Methods | Description | | Methods | Description |
| ------- | ----------- | |:-------------------------------------------|:------------------------------------------------------|
| `-H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK"` | Use this method as is, whenever authentication needed | | `-H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK"` | Use this method as is, whenever authentication needed |
| `-X POST` | Use this method when creating new objects | | `-X POST` | Use this method when creating new objects |
| `-X PUT` | Use this method when updating existing objects | | `-X PUT` | Use this method when updating existing objects |
......
doc/development/documentation/workflow.md
View file @ 0df7adef
...@@ -7,16 +7,16 @@ description: Learn the process of shipping documentation for GitLab. ...@@ -7,16 +7,16 @@ description: Learn the process of shipping documentation for 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. 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, - Product Managers (PMs): in the issue for all new and updated features,
PMs include specific documentation requirements that the developer who is PMs include specific documentation requirements that the developer who is
writing or updating the docs must meet, along with feature descriptions writing or updating the docs must meet, along with feature descriptions
and use cases. They call out any specific areas where collaborating with and use cases. They call out any specific areas where collaborating with
a technical writer is recommended, and usually act as the first reviewer a technical writer is recommended, and usually act as the first reviewer
of the docs. of the docs.
- Developers: author documentation and merge it on time (up to a week after - Developers: author documentation and merge it on time (up to a week after
the feature freeze). the feature freeze).
- Technical Writers: review each issue to ensure PM's requirements are complete, - 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 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. reviewer of all new and updated docs content before it's merged.
## Requirements ## Requirements
...@@ -112,17 +112,17 @@ and the missed-deliverable due date (the 14th of each month) are both respected. ...@@ -112,17 +112,17 @@ and the missed-deliverable due date (the 14th of each month) are both respected.
The developer should add to the feature MR the documentation containing: The developer should add to the feature MR the documentation containing:
- The [documentation blurb](structure.md#documentation-blurb): copy the - The [documentation blurb](structure.md#documentation-blurb): copy the
feature name, overview/description, and use cases from the feature issue feature name, overview/description, and use cases from the feature issue
- Instructions: write how to use the feature, step by step, with no gaps. - Instructions: write how to use the feature, step by step, with no gaps.
- [Crosslink for discoverability](structure.md#discoverability): link with - [Crosslink for discoverability](structure.md#discoverability): link with
internal docs and external resources (if applicable) internal docs and external resources (if applicable)
- Index: link the new doc or the new heading from the higher-level index - Index: link the new doc or the new heading from the higher-level index
for [discoverability](#discoverability) for [discoverability](#discoverability)
- [Screenshots](styleguide.md#images): when necessary, add screenshots for: - [Screenshots](styleguide.md#images): when necessary, add screenshots for:
- Illustrating a step of the process - Illustrating a step of the process
- Indicating the location of a navigation menu - Indicating the location of a navigation menu
- Label the MR with `Documentation`, `Deliverable`, `docs-P1`, and assign - Label the MR with `Documentation`, `Deliverable`, `docs-P1`, and assign
the correct milestone the correct milestone
- Assign the PM for review - Assign the PM for review
- When done, mention the `@gl\-docsteam` in the MR asking for review - When done, mention the `@gl\-docsteam` in the MR asking for review
- **Due date**: feature freeze date and time - **Due date**: feature freeze date and time
...@@ -133,10 +133,10 @@ If the docs aren't being shipped within the feature MR: ...@@ -133,10 +133,10 @@ 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) - 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>` - Label the issue with: `Documentation`, `Deliverable`, `docs-P1`, `<product-label>`
(product label == CI/CD, Pages, Prometheus, etc) (product label == CI/CD, Pages, Prometheus, etc)
- Add the correct milestone - Add the correct milestone
- Create a new MR for shipping the docs changes and follow the same - Create a new MR for shipping the docs changes and follow the same
process [described above](#documentation-shipped-in-the-feature-mr) process [described above](#documentation-shipped-in-the-feature-mr)
- Use the MR description template called "Documentation" - Use the MR description template called "Documentation"
- Add the same labels and milestone as you did for the issue - Add the same labels and milestone as you did for the issue
- Assign the PM for review - Assign the PM for review
...@@ -162,9 +162,9 @@ The **due date** for **merging** `missed-deliverable` MRs is on the ...@@ -162,9 +162,9 @@ The **due date** for **merging** `missed-deliverable` MRs is on the
- **Planning** - **Planning**
- Once an issue contains a Documentation label and the current milestone, a - Once an issue contains a Documentation label and the current milestone, a
technical writer reviews the Product Manager's documentation requirements technical writer reviews the Product Manager's documentation requirements.
- Once the documentation requirements are approved, the technical writer can - Once the documentation requirements are approved, the technical writer can
work with the developer to discuss any documentation questions and plans/outlines, as needed. work with the developer to discuss any documentation questions and plans/outlines, as needed.
- **Review** - A technical writer must review the documentation for: - **Review** - A technical writer must review the documentation for:
- Clarity - Clarity
...@@ -183,4 +183,3 @@ work with the developer to discuss any documentation questions and plans/outline ...@@ -183,4 +183,3 @@ work with the developer to discuss any documentation questions and plans/outline
- Describe the difference between new features and feature updates - Describe the difference between new features and feature updates
- Creating a new doc vs updating an existing doc - Creating a new doc vs updating an existing doc
--> -->
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7