diff options
Diffstat (limited to 'doc/development/documentation')
| -rw-r--r-- | doc/development/documentation/index.md | 266 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/global_nav.md | 22 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/index.md | 8 | ||||
| -rw-r--r-- | doc/development/documentation/structure.md | 11 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide.md | 155 |
5 files changed, 318 insertions, 144 deletions
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index f845a6ec592..2ea26985fcf 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -26,7 +26,7 @@ The source of the documentation exists within the codebase of each GitLab applic | --- | --- | | [GitLab](https://gitlab.com/gitlab-org/gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab/tree/master/doc) | | [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/) | [`/docs`](https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs) | -| [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab/tree/master/doc) | +| [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc) | | [Charts](https://gitlab.com/gitlab-org/charts/gitlab) | [`/doc`](https://gitlab.com/gitlab-org/charts/gitlab/tree/master/doc) | Documentation issues and merge requests are part of their respective repositories and all have the label `Documentation`. @@ -70,7 +70,28 @@ See the [Structure](styleguide.md#structure) section of the [Documentation Style ## Metadata To provide additional directives or useful information, we add metadata in YAML -format to the beginning of each product documentation page. +format to the beginning of each product documentation page (YAML front matter). +All values are treated as strings and are only used for the +[docs website](site_architecture/index.md). + +### Stage and group metadata + +Each page should ideally have metadata related to the stage and group it +belongs to, as well as an information block as described below: + +- `stage`: The [Stage](https://about.gitlab.com/handbook/product/product-categories/#devops-stages) + to which the majority of the page's content belongs. +- `group`: The [Group](https://about.gitlab.com/company/team/structure/#product-groups) + to which the majority of the page's content belongs. +- `info`: The following line, which provides direction to contributors regarding + how to contact the Technical Writer associated with the page's Stage and + Group: + + ```plaintext + To determine the technical writer assigned to the Stage/Group + associated with this page, see + https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers + ``` For example, the following metadata would be at the beginning of a product documentation page whose content is primarily associated with the Audit Events @@ -84,24 +105,64 @@ info: To determine the technical writer assigned to the Stage/Group associated w --- ``` -The following list describes the YAML parameters in use: +### Page type metadata + +Originally discussed in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/1280), +each page should have a `type` metadata. It can be one or more of the following: + +- `index`: Index/overview pages. They serve as a list to other pages. Doesn't + necessarily mean the page should be named `index.md`. [Example page](../../install/README.md). +- `concepts`: What you need to know before using product. Informational, not + instructional. For example, abstract ideas, explain meaning or benefit, support + understanding of tasks. They are read for background information, for example + "Why X is important". [Example page](../../topics/autodevops/index.md). +- `howto`: Specific use case instructions. [Example page](../../ssh/README.md). +- `tutorial`: Learn a process/concept by doing. [Example page](../../gitlab-basics/start-using-git.md). +- `reference`: Covers what things are/do. Things like specific settings, facts + without too much explanation that are read for detailed information. + [Example page](../../ci/yaml/README.md). + +### Redirection metadata + +The following metadata should be added when a page is moved to another location: - `redirect_to`: The relative path and filename (with an `.md` extension) of the location to which visitors should be redirected for a moved page. [Learn more](#changing-document-location). -- `stage`: The [Stage](https://about.gitlab.com/handbook/product/categories/#devops-stages) - to which the majority of the page's content belongs. -- `group`: The [Group](https://about.gitlab.com/company/team/structure/#product-groups) - to which the majority of the page's content belongs. -- `info`: The following line, which provides direction to contributors regarding - how to contact the Technical Writer associated with the page's Stage and - Group: `To determine the technical writer assigned to the Stage/Group - associated with this page, see - https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers` - `disqus_identifier`: Identifier for Disqus commenting system. Used to keep comments with a page that's been moved to a new URL. [Learn more](#redirections-for-pages-with-disqus-comments). +### Comments metadata + +The [docs website](site_architecture/index.md) has comments (provided by Disqus) +enabled by default. In case you want to disable them (for example in index pages), +set it to `false`: + +```yaml +--- +comments: false +--- +``` + +### Additional page metadata + +Each page can have additional (optional) metadata (set in the +[default.html](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/fc3577921343173d589dfa43d837b4307e4e620f/layouts/default.html#L30-52) +Nanoc layout), which will be shown to the top of the page if defined: + +- `author`: The name of the author of a page, usually a tutorial. It requires `author_gitlab` in order to be shown. +- `author_gitlab`: The username of the author on GitLab.com. It requires `author` in order to be shown. +- `date`: The date the page was created, usually for tutorials. +- `article_type`: The type of article. Can be either `tutorial` or `user guide`. +- `level`: The level of complexity of a how-to or tutorial. Can be either `beginner`, + `advanced`, or `intermediate`. +- `last_updated`: The date in ISO format when the page was last updated. For example `2020-02-14`. +- `reading_time`: If you want to add an indication of the approximate reading + time of a page, you can set `reading_time` to `true`. This uses a simple + [algorithm](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/lib/helpers/reading_time.rb) + to calculate the reading time based on the number of words. + ## Changing document location Changing a document's location requires specific steps to ensure that @@ -226,9 +287,6 @@ it increases the work of the release managers. Every GitLab instance includes the documentation, which is available at `/help` (`https://gitlab.example.com/help`). For example, <https://gitlab.com/help>. -There are [plans](https://gitlab.com/groups/gitlab-org/-/epics/693) to end this -practice and instead link out from the GitLab application to <https://docs.gitlab.com> URLs. - The documentation available online on <https://docs.gitlab.com> is deployed every four hours from the `master` branch of GitLab, Omnibus, and Runner. Therefore, after a merge request gets merged, it will be available online on the same day. However, it will be shipped (and available on `/help`) within the milestone assigned @@ -492,122 +550,138 @@ The output should be similar to: Note that this requires you to either have the required lint tools installed on your machine, or a working Docker installation, in which case an image with these tools pre-installed will be used. -### Local linting +### Local linters To help adhere to the [documentation style guidelines](styleguide.md), and improve the content -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. - -Running the following locally allows you to match the checks in the build pipeline: +added to documentation, [install documentation linters](#install-linters) and +[integrate them with your code editor](#configure-editors). -- [markdownlint](#markdownlint). -- [Vale](#vale). +At GitLab, we mostly use: -NOTE: **Note:** -This list does not limit what other linters you can add to your local documentation writing toolchain. +- [markdownlint](#markdownlint) +- [Vale](#vale) #### markdownlint -[markdownlint](https://github.com/DavidAnson/markdownlint) checks that Markdown -syntax follows [certain rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules), -and is used by the [`docs-lint` test](#testing) with a [configuration file](#markdownlint-configuration). -Our [Documentation Style Guide](styleguide.md#markdown) and [Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/) -elaborate on which choices must be made when selecting Markdown syntax for GitLab -documentation. This tool helps catch deviations from those guidelines. - -markdownlint can be used [on the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--), -either on a single Markdown file or on all Markdown files in a project. For example, to run -markdownlint on all documentation in the [`gitlab` project](https://gitlab.com/gitlab-org/gitlab), -run the following commands from within your `gitlab` project root directory, which will -automatically detect the [`.markdownlint.json`](#markdownlint-configuration) configuration -file in the root of the project, and test all files in `/doc` and its subdirectories: - -```shell -markdownlint 'doc/**/*.md' -``` +[markdownlint](https://github.com/DavidAnson/markdownlint) checks that Markdown syntax follows +[certain rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules), and is +used by the [`docs-lint` test](#testing). -If you wish to use a different configuration file, use the `-c` flag: +Our [Documentation Style Guide](styleguide.md#markdown) and +[Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/) elaborate on which choices must +be made when selecting Markdown syntax for GitLab documentation. This tool helps catch deviations +from those guidelines. -```shell -markdownlint -c <config-file-name> 'doc/**/*.md' -``` +markdownlint configuration is found in the following projects: -##### Run markdownlint in an editor +- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.markdownlint.json) +- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/.markdownlint.json) +- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/.markdownlint.json) +- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.markdownlint.json) +- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/.markdownlint.json) -markdownlint can also be run as a linter within text editors using [plugins/extensions](https://github.com/DavidAnson/markdownlint#related), -such as: +This configuration is also used within build pipelines. -- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint) -- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) -- [Atom](https://atom.io/packages/linter-node-markdownlint) +You can use markdownlint: -It is best to use the [same configuration file](#markdownlint-configuration) as what -is in use in the four repositories that are the sources for <https://docs.gitlab.com>. Each -plugin/extension has different requirements regarding the configuration file, which -is explained in each editor's docs. +- [On the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--). +- [Within a code editor](#configure-editors). -##### markdownlint configuration +#### Vale -Each formatting issue that markdownlint checks has an associated -[rule](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules). -These rules are configured in the `.markdownlint.json` files located in the root of -four repositories that are the sources for <https://docs.gitlab.com>: +[Vale](https://errata-ai.gitbook.io/vale/) is a grammar, style, and word usage linter for the +English language. Vale's configuration is stored in the +[`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/blob/master/.vale.ini) file located in the root +directory of projects. -- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.markdownlint.json) -- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/.markdownlint.json) -- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/.markdownlint.json) -- [`charts`](https://gitlab.com/charts/gitlab/blob/master/.markdownlint.json) +Vale supports creating [custom tests](https://errata-ai.github.io/vale/styles/) that extend any of +several types of checks, which we store in the `.linting/vale/styles/gitlab` directory within the +documentation directory of projects. -By default all rules are enabled, so the configuration file is used to disable unwanted -rules, and also to configure optional parameters for enabled rules as needed. You can -also check [the issue](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64352) that -tracked the changes required to implement these rules, and details which rules were -on or off when markdownlint was enabled on the docs. +Vale configuration is found in the following projects: -#### Vale +- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.vale/gitlab) +- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/master/docs/.vale/gitlab) +- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/tree/master/doc/.vale/gitlab) +- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/tree/master/doc/.vale/gitlab) +- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/master/doc/.vale/gitlab) -[Vale](https://errata-ai.gitbook.io/vale/) is a grammar, style, and word usage linter -for the English language. Vale's configuration is stored in the -[`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/blob/master/.vale.ini) file -located in the root directory of the [GitLab repository](https://gitlab.com/gitlab-org/gitlab). +This configuration is also used within build pipelines. -Vale supports creating [custom tests](https://errata-ai.github.io/vale/styles/), -stored in the `doc/.linting/vale/styles/gitlab` directory, that extend any of -several types of checks. +You can use Vale: -To view linting suggestions locally, you must install Vale on your own machine, -and from GitLab's root directory (where `.vale.ini` is located), run: +- [On the command line](https://errata-ai.gitbook.io/vale/getting-started/usage). +- [Within a code editor](#configure-editors). -```shell -vale --glob='*.{md}' doc -``` +#### Install linters + +At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in +build pipelines: -Vale's error-level test results [are displayed](#testing) in CI pipelines. +1. Install `markdownlint-cli`, using either: -##### Run Vale in an editor + - `npm`: + + ```shell + npm install -g markdownlint-cli + ``` + + - `yarn`: + + ```shell + yarn global add markdownlint-cli + ``` + + We recommend installing the version of `markdownlint-cli` currently used in the documentation + linting [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/dockerfiles/Dockerfile.gitlab-docs-lint#L38). + +1. Install [`vale`](https://github.com/errata-ai/vale/releases). For example, to install using + `brew` for macOS, run: + + ```shell + brew install vale + ``` + + We recommend installing the version of Vale currently used in the documentation linting + [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/dockerfiles/Dockerfile.gitlab-docs-lint#L16). + +In addition to using markdownlint and Vale at the command line, these tools can be +[integrated with your code editor](#configure-editors). + +#### Configure editors + +To configure markdownlint within your editor, install one of the following as appropriate: + +- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint) +- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) +- [Atom](https://atom.io/packages/linter-node-markdownlint) -You can run Vale as a linter within your text editor of choice, with: +To configure Vale within your editor, install one of the following as appropriate: - The Sublime Text [`SublimeLinter-contrib-vale` plugin](https://packagecontrol.io/packages/SublimeLinter-contrib-vale) - The Visual Studio Code [`testthedocs.vale` extension](https://marketplace.visualstudio.com/items?itemName=testthedocs.vale) We don't use [Vale Server](https://errata-ai.github.io/vale/#using-vale-with-a-text-editor-or-another-third-party-application). -##### Disable a Vale test +#### Disable Vale tests -You can disable a specific Vale linting rule or all Vale linting rules for any portion of a document: +You can disable a specific Vale linting rule or all Vale linting rules for any portion of a +document: -- To disable a specific rule, add a `<!-- vale gitlab.rulename = NO -->` tag - before the text, and a `<!-- vale gitlab.rulename = YES -->` tag after the text, - replacing `rulename` with the filename of a test in the [GitLab styles](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.linting/vale/styles/gitlab) directory. -- To disable all Vale linting rules, add a `<!-- vale off -->` tag before the text, - and a `<!-- vale on -->` tag after the text. +- To disable a specific rule, add a `<!-- vale gitlab.rulename = NO -->` tag before the text, and a + `<!-- vale gitlab.rulename = YES -->` tag after the text, replacing `rulename` with the filename + of a test in the + [GitLab styles](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.linting/vale/styles/gitlab) + directory. +- To disable all Vale linting rules, add a `<!-- vale off -->` tag before the text, and a + `<!-- vale on -->` tag after the text. -Whenever possible, exclude only the problematic rule and line(s). -In some cases, such as list items, you may need to disable linting for the entire -list until ["Ignore comments are not honored in a Markdown file"](https://github.com/errata-ai/vale/issues/175) is resolved. +Whenever possible, exclude only the problematic rule and line(s). In some cases, such as list items, +you may need to disable linting for the entire list until +[Vale issue #175](https://github.com/errata-ai/vale/issues/175) is resolved. -For more information, see [Vale's documentation](https://errata-ai.gitbook.io/vale/getting-started/markup#markup-based-configuration). +For more information, see +[Vale's documentation](https://errata-ai.gitbook.io/vale/getting-started/markup#markup-based-configuration). ## Danger Bot diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md index 71020e6054e..2625fbe0415 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -16,6 +16,22 @@ Global navigation (the left-most pane in our three pane documentation) provides: - The ability to refine landing pages, so they don't have to do all the work of surfacing every page contained within the documentation. +## Quick start + +To add a topic to the global nav, go to the directory that contains +[navigation files](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/content/_data/) +and edit the `yaml` file for your product area. You can copy an existing nav entry and +edit it to point to your topic. + +The files are: + +| File | Document | Location | +|-----------------------|--------------------------------------------------------------------|-------------------------------------------------------| +| `charts-nav.yaml` | GitLab cloud native Helm Chart | `https://docs.gitlab.com/charts/` | +| `default-nav.yaml` | GitLab Docs | `https://docs.gitlab.com/ee/` | +| `omnibus-nav.yaml` | Omnibus GitLab Docs | `https://docs.gitlab.com/omnibus/` | +| `runner-nav.yaml` | GitLab Runner Docs | `https://docs.gitlab.com/runner/` | + ## Adding new items All new pages need a new navigation item. Without a navigation, the page becomes "orphaned". That @@ -98,7 +114,7 @@ for clarity. To see the improvements planned, check the [global nav epic](https://gitlab.com/groups/gitlab-com/-/epics/21). -CAUTION: **Attention!** +NOTE: **Note:** **Do not** [add items](#adding-new-items) to the global nav without the consent of one of the technical writers. @@ -275,7 +291,7 @@ and the following syntax rules. an "information" icon on the nav to make the user aware that the feature is EE-only. -DANGER: **Important!** +CAUTION: **Caution:** All links present on the data file must end in `.html`, not `.md`. Do not start any relative link with a forward slash `/`. @@ -290,7 +306,7 @@ Examples: docs: - doc_title: Service Desk doc_url: 'user/project/service_desk.html' - ee_only: true + ee_only: false # note that the URL above ends in html and, as the # document is EE-only, the attribute ee_only is set to true. ``` diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 942b202a3ec..60e6d4bcb13 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -111,7 +111,7 @@ located in the [Dockerfiles directory](https://gitlab.com/gitlab-org/gitlab-docs If you need to rebuild the Docker images immediately (must have maintainer level permissions): -CAUTION: **Caution** +CAUTION: **Caution:** If you change the dockerfile configuration and rebuild the images, you can break the master pipeline in the main `gitlab` repository as well as in `gitlab-docs`. Create an image with a different name first and test it to ensure you do not break the pipelines. @@ -152,9 +152,9 @@ Suppose we have the `content/_data/versions.yaml` file with the content: ```yaml versions: -- 10.6 -- 10.5 -- 10.4 + - 10.6 + - 10.5 + - 10.4 ``` We can then loop over the `versions` array with something like: diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index eadcedfaac0..4cfc57aa57b 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -20,7 +20,7 @@ Every feature or use case document should include the following content in the f with exceptions and details noted below and in the template included on this page. - **Title**: Top-level heading with the feature name, or a use case name, which would start with - a verb, like Configuring, Enabling, and so on. + a verb, like "Configure", "Enable", and so on. - **Introduction**: A couple sentences about the subject matter and what's to be found on this page. Describe what the feature or topic is, what it does, and in what context it should be used. There is no need to add a title called "Introduction" or "Overview," because people rarely @@ -47,10 +47,13 @@ When done, remove all of this commented-out text, except a commented-out Trouble which, if empty, can be left in place to encourage future use.--> --- description: "Short document description." # Up to ~200 chars long. They will be displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here. +stage: "Add the stage name here, and remove the quotation marks" +group: "Add the group name here, and remove the quotation marks" +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Feature Name or Use Case Name **[TIER]** (1) -<!--If writing about a use case, drop the tier, and start with a verb, e.g. 'Configuring', 'Implementing', + the goal/scenario--> +<!--If writing about a use case, drop the tier, and start with a verb, e.g. "Configure", "Implement", + the goal/scenario--> <!--For pages on newly introduced features, add the following line. If only some aspects of the feature have been introduced, specify what parts of the feature.--> > [Introduced](link_to_issue_or_mr) in GitLab (Tier) X.Y (2). @@ -99,12 +102,12 @@ Larger instruction sets may have subsections covering specific phases of the pro Where appropriate, provide examples of code or configuration files to better clarify intended usage. - Write a step-by-step guide, with no gaps between the steps. -- Include example code or configurations as part of the relevant step. Use appropriate markdown to [wrap code blocks with syntax highlighting](../../user/markdown.md#colored-code-and-syntax-highlighting). +- Include example code or configurations as part of the relevant step. Use appropriate Markdown to [wrap code blocks with syntax highlighting](../../user/markdown.md#colored-code-and-syntax-highlighting). - Start with an h2 (`##`), break complex steps into small steps using subheadings h3 > h4 > h5 > h6. _Never skip a 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 like `## Configuring X` for instructions when the feature +single heading like `## Configure X` for instructions when the feature is simple and the document is short. <!-- ## Troubleshooting diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 9a93dbf4f94..f2c90e71bd5 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -88,7 +88,7 @@ New information that would be useful toward the future usage or troubleshooting The more we reflexively add useful information to the docs, the more (and more successfully) the docs will be used to efficiently accomplish tasks and solve problems. -If you have questions when considering, authoring, or editing docs, ask the Technical Writing team on Slack in `#docs` or in GitLab by mentioning the writer for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). Otherwise, forge ahead with your best effort. It does not need to be perfect; the team is happy to review and improve upon your content. Please review the [Documentation guidelines](index.md) before you begin your first documentation MR. +If you have questions when considering, authoring, or editing docs, ask the Technical Writing team on Slack in `#docs` or in GitLab by mentioning the writer for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/product-categories/#devops-stages). Otherwise, forge ahead with your best effort. It does not need to be perfect; the team is happy to review and improve upon your content. Please review the [Documentation guidelines](index.md) before you begin your first documentation MR. Having a knowledge base in any form that is separate from the documentation would be against the docs-first methodology because the content would overlap with the documentation. @@ -325,9 +325,22 @@ tenses, words, and phrases: - Avoid using the word *currently* when talking about the product or its features. The documentation describes the product as it is, and not as it will be at some indeterminate point in the future. +- Avoid the using the word *scalability* with increasing GitLab's performance + for additional users. Using the words *scale* or *scaling* in other cases is + acceptable, but references to increasing GitLab's performance for additional + users should direct readers to the GitLab + [reference architectures](../../administration/reference_architectures/index.md) + page. +- Avoid all forms of the phrases *high availability* and *HA*, and instead + direct readers to the GitLab [reference architectures](../../administration/reference_architectures/index.md) + for information about configuring GitLab to have the performance needed for + additional users over time. - Don't use profanity or obscenities. Doing so may negatively affect other users and contributors, which is contrary to GitLab's value of - [diversity and inclusion](https://about.gitlab.com/handbook/values/#diversity-inclusion). + [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). +- Avoid the use of [racially-insensitive terminology or phrases](https://www.marketplace.org/2020/06/17/tech-companies-update-language-to-avoid-offensive-terms/). For example: + - Use *primary* and *secondary* for database and server relationships. + - Use *allowlist* and *denylist* to describe access control lists. ### Word usage clarifications @@ -662,7 +675,7 @@ For other punctuation rules, please refer to the - Avoid adding things that show ephemeral statuses. For example, if a feature is considered beta or experimental, put this information in a note, not in the heading. - When introducing a new document, be careful for the headings to be - grammatically and syntactically correct. Mention an [assigned technical writer (TW)](https://about.gitlab.com/handbook/product/categories/) + grammatically and syntactically correct. Mention an [assigned technical writer (TW)](https://about.gitlab.com/handbook/product/product-categories/) for review. This is to ensure that no document with wrong heading is going live without an audit, thus preventing dead links and redirection issues when @@ -750,6 +763,15 @@ _Internal_ refers to documentation in the same project. When linking to document separate projects (for example, linking to Omnibus docs from GitLab docs), you must use absolute URLs. +Do not use absolute URLs like `https://docs.gitlab.com/ee/index.html` to crosslink +to other docs within the same project. Use relative links to the file, like `../index.md`. (These are converted to HTML when the site is rendered.) + +Relative linking enables crosslinks to work: + +- in Review Apps, local previews, and `/help`. +- when working on the docs locally, so you can verify that they work as early as possible in the process. +- within the GitLab UI when browsing doc files in their respective repositories. For example, the links displayed at `https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/README.md`. + To link to internal documentation: - Use relative links to Markdown files in the same repository. @@ -778,7 +800,7 @@ To link to internal documentation: - `../../issues/tags.md` - `../../issues/tags.md#stages` -NOTE: **Note**: +NOTE: **Note:** Using the Markdown extension is necessary for the [`/help`](index.md#gitlab-help) section of GitLab. ### Links to external documentation @@ -839,19 +861,42 @@ To indicate the steps of navigation through the UI: ## Images +Images, including screenshots, can help a reader better understand a concept. +However, they can be hard to maintain, and should be used sparingly. + +Before including an image in the documentation, ensure it provides value to the reader. + +### Capture the image + +Use images to help the reader understand where they are in a process, or how they need to +interact with the application. + +When you take screenshots: + +- *Capture the most relevant area of the page.* Don't include unnecessary white + space or areas of the page that don't help illustrate your point. Also, don't + include the entire page if you don't have to, but also ensure the image + contains enough information to allow the user to determine where things are. +- *Be consistent.* Find a browser window size that works for you that also + displays all areas of the product, including the left navigation (usually > + 1200px wide). For consistency, use this browser window size for your + screenshots by installing a browser extension for setting a window to a + specific size (for example, + [Window Resizer](https://chrome.google.com/webstore/detail/window-resizer/kkelicaakdanhinjdeammmilcgefonfh/related?hl=en) + for Google Chrome). + +### Save the image + +- Save the image with a lowercase file name that is descriptive of the feature + or concept in the image. If the image is of the GitLab interface, append the + GitLab version to the file name, based on the following format: + `image_name_vX_Y.png`. For example, for a screenshot taken from the pipelines + page of GitLab 11.1, a valid name is `pipelines_v11_1.png`. If you're adding an + illustration that doesn't include parts of the user interface, add the release + number corresponding to the release the image was added to; for an MR added to + 11.1's milestone, a valid name for an illustration is `devops_diagram_v11_1.png`. - Place images in a separate directory named `img/` in the same directory where the `.md` document that you're working on is located. -- Images should have a specific, non-generic name that will - differentiate and describe them properly. -- For screenshots of GitLab software, append the GitLab version the screenshot was taken from to the - file name. Use the following format: `image_name_vX_Y.png`. -- For example, for a screenshot taken from the pipelines page of - GitLab 11.1, a valid name is `pipelines_v11_1.png`. If you're - adding an illustration that does not include parts of the UI, - add the release number corresponding to the release the image - was added to. Example, for an MR added to 11.1's milestone, - a valid name for an illustration is `devops_diagram_v11_1.png`. -- Keep all file names in lower case. - Consider using PNG images instead of JPEG. - [Compress all PNG images](#compress-images). - Compress gifs with <https://ezgif.com/optimize> or similar tool. @@ -860,15 +905,20 @@ To indicate the steps of navigation through the UI: - Max image size: 100KB (gifs included). - See also how to link and embed [videos](#videos) to illustrate the docs. -Inside the document: +### Add the image link to content + +The Markdown code for including an image in a document is: +`` + +The image description is the alt text for the rendered image on the docs site. +For accessibility and SEO, use [descriptions](https://webaim.org/techniques/alttext/) +that: + +- Are accurate, succinct, and unique. +- Don't use *image of …* or *graphic of…* to describe the image. -- The Markdown way of using an image inside a document is: - `` -- Always use a proper description for what the image is about. That way, when a - browser fails to show the image, this text will be used as an alternative - description. -- If a heading is placed right after an image, always add three dashes (`---`) - between the image and the heading. +Also, if a heading immediately follows an image, be sure to add three dashes +(`---`) between the image and the heading. ### Remove image shadow @@ -1133,8 +1183,8 @@ The following are examples of source Markdown for menu items with their publishe Whenever you need to call special attention to particular sentences, use the following markup for highlighting. -_Note that the alert boxes only work for one paragraph only. Multiple paragraphs, -lists, headers and so on, will not render correctly. For multiple lines, use blockquotes instead._ +Note that the alert boxes only work for one paragraph only. Multiple paragraphs, +lists, headers and so on, will not render correctly. For multiple lines, use [blockquotes](#blockquotes) instead. Alert boxes only render on the GitLab Docs site (<https://docs.gitlab.com>). Within GitLab itself, they will appear as plain Markdown text (like the examples @@ -1271,20 +1321,20 @@ The following are styles to follow when describing UI elements on a screen: ### Verbs for UI elements -The following are recommended verbs for specific uses. +The following are recommended verbs for specific uses with UI elements: -| Recommended | Used for | Alternatives | -|:------------|:---------------------------|:---------------------------| -| "click" | buttons, links, menu items | "hit", "press", "select" | -| "check" | checkboxes | "enable", "click", "press" | -| "select" | dropdowns | "pick" | -| "expand" | expandable sections | "open" | +| Recommended | Used for | Replaces | +|:--------------------|:---------------------------|:---------------------------| +| *click* | buttons, links, menu items | "hit", "press", "select" | +| *select* or *clear* | checkboxes | "enable", "click", "press" | +| *select* | dropdowns | "pick" | +| *expand* | expandable sections | "open" | ### Other Verbs -| Recommended | Used for | Alternatives | -|:------------|:--------------------------------|:-------------------| -| "go" | making a browser go to location | "navigate", "open" | +| Recommended | Used for | Replaces | +|:------------|:--------------------------------|:----------------------| +| *go to* | making a browser go to location | "navigate to", "open" | ## GitLab versions and tiers @@ -1296,6 +1346,11 @@ Tagged and released versions of GitLab documentation are available: The version introducing a new feature is added to the top of the topic in the documentation to provide a helpful link back to how the feature was developed. +TIP: **Tip:** +Whenever you have documentation related to the `gitlab.rb` file, you're working with a self-managed installation. +The section or page is therefore likely to apply only to self-managed instances. +If so, the relevant "`TIER` ONLY" [Product badge](#product-badges) should be included at the highest applicable heading level. + ### Text for documentation requiring version text - For features that need to declare the GitLab version that the feature was introduced. Text similar @@ -1327,6 +1382,22 @@ a helpful link back to how the feature was developed. > - [Moved](<link-to-issue>) to GitLab Core in 12.0. ``` +- If a feature is deprecated, include a link to a replacement (when available): + + ```markdown + > - [Deprecated](<link-to-issue>) in GitLab 11.3. Replaced by [meaningful text](<link-to-appropriate-documentation>). + ``` + + It's also acceptable to describe the replacement in surrounding text, if available. + + If the deprecation is not obvious in existing text, you may want to include a warning such as: + + ```markdown + CAUTION: **Warning:** + This feature was [deprecated](link-to-issue) in GitLab 12.3 + and replaced by [Feature name](link-to-feature-documentation). + ``` + NOTE: **Note:** Version text must be on its own line and surrounded by blank lines to render correctly. @@ -1389,7 +1460,7 @@ lines with an inserted line break. Splitting product or feature names across lines makes searching for these items more difficult, and can cause problems if names change. -For example, the followng Markdown content is *not* formatted correctly: +For example, the following Markdown content is *not* formatted correctly: ```markdown When entering a product or feature name that includes a space (such as GitLab @@ -1430,7 +1501,7 @@ For GitLab.com only tiers (when the feature is not available for self-managed in The tier should be ideally added to headers, so that the full badge will be displayed. 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 that will show the tiers on hover. +the tier mention will be represented by an orange info icon **(information)** that will show the tiers on hover. Use the lowest tier at the page level, even if higher-level tiers exist on the page. For example, you might have a page that is marked as Starter but a section badged as Premium. @@ -1542,6 +1613,9 @@ can facilitate this by making sure the troubleshooting content addresses: 1. How the user can confirm they have the problem. 1. Steps the user can take towards resolution of the problem. +If the contents of each category can be summarized in one line and a list of steps aren't required, consider setting up a +[table](#tables) with headers of *Problem* \| *Cause* \| *Solution* (or *Workaround* if the fix is temporary), or *Error message* \| *Solution*. + ## Feature flags Learn how to [document features deployed behind flags](feature_flags.md). @@ -1607,6 +1681,13 @@ and email address of a user. Don't use real user information in API calls: - **Names**: Use strings like `Example Username`. Alternatively, use diverse or non-gendered names with common surnames, such as `Sidney Jones`, `Zhang Wei`. or `Maria Garcia`. +### Fake URLs + +When including sample URLs in the documentation, use: + +- `example.com` when the domain name is generic. +- `gitlab.example.com` when referring to self-managed instances of GitLab. + ### Fake tokens There may be times where a token is needed to demonstrate an API call using |