kotovalexarian-likes-gitlab/gitlab-org--gitlab-foss

GitLab Bot 04a7fe4f4b Add latest changes from gitlab-org/gitlab@master

2021-10-12 18:12:42 +00:00

19 KiB

Raw Blame History

stage	group	info	description
none	Documentation Guidelines	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments	Learn how to contribute to GitLab Documentation.

Documentation testing

GitLab documentation is stored in projects with code and treated like code. Therefore, we use processes similar to those used for code to maintain standards and quality of documentation.

We have tests:

To lint the words and structure of the documentation.
To check the validity of internal links within the documentation suite.
To check the validity of links from UI elements, such as files in app/views files.

For the specifics of each test run in our CI/CD pipelines, see the configuration for those tests in the relevant projects:

Run tests locally

Similar to previewing your changes locally, you can also run these tests on your local computer. This has the advantage of:

Speeding up the feedback loop. You can know of any problems with the changes in your branch without waiting for a CI/CD pipeline to run.
Lowering costs. Running tests locally is cheaper than running tests on the cloud infrastructure GitLab uses.

To run tests locally, it's important to:

Install the tools, and keep them up to date.
Run linters, documentation link tests, and UI link tests the same way they are run in CI/CD pipelines. It's important to use same configuration we use in CI/CD pipelines, which can be different than the default configuration of the tool.

Lint checks

Lint checks are performed by the lint-doc.sh script and can be executed as follows:

Navigate to the gitlab directory.

Run:

MD_DOC_PATH=path/to/my_doc.md scripts/lint-doc.sh

Where MD_DOC_PATH points to the file or directory you would like to run lint checks for. If you omit it completely, it defaults to the doc/ directory. The output should be similar to:

=> Linting documents at path /path/to/gitlab as <user>...
=> Checking for cURL short options...
=> Checking for CHANGELOG.md duplicate entries...
=> Checking /path/to/gitlab/doc for executable permissions...
=> Checking for new README.md files...
=> Linting markdown style...
=> Linting prose...
✔ 0 errors, 0 warnings and 0 suggestions in 1 file.
✔ Linting passed

This requires you to either:

Have the required lint tools installed on your computer.
A working Docker installation, in which case an image with these tools pre-installed is used.

Documentation link tests

To execute documentation link tests locally:

Navigate to the gitlab-docs directory.

Run the following commands:

# Check for broken internal links
bundle exec nanoc check internal_links

# Check for broken external links (might take a lot of time to complete).
# This test is set to be allowed to fail and is run only in the gitlab-docs project CI
bundle exec nanoc check internal_anchors

UI link tests

The ui-docs-links lint job uses haml-lint to test that all documentation links from UI elements (app/views files, for example) are linking to valid pages and anchors.

To run the ui-docs-links test locally:

Open the gitlab directory in a terminal window.

Run:

bundle exec haml-lint -i DocumentationLinks

If you receive an error the first time you run this test, run bundle install, which installs the dependencies for GitLab, and try again.

If you don't want to install all of the dependencies to test the links, you can:

Open the gitlab directory in a terminal window.
Install haml-lint:
```
gem install haml_lint
```
Run:
```
haml-lint -i DocumentationLinks
```

If you manually install haml-lint with this process, it does not update automatically and you should make sure your version matches the version used by GitLab.

Local linters

To help adhere to the documentation style guidelines, and improve the content added to documentation, install documentation linters and integrate them with your code editor.

At GitLab, we mostly use:

markdownlint
Vale

markdownlint

markdownlint checks that Markdown syntax follows certain rules, and is used by the docs-lint test.

Our Documentation Style Guide and 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 configuration is found in the following projects:

This configuration is also used in build pipelines.

You can use markdownlint:

On the command line.
In a code editor.
In a pre-push hook.

Vale

Vale is a grammar, style, and word usage linter for the English language. Vale's configuration is stored in the .vale.ini file located in the root directory of projects.

Vale supports creating custom tests that extend any of several types of checks, which we store in the .linting/vale/styles/gitlab directory in the documentation directory of projects.

You can find Vale configuration in the following projects:

This configuration is also used in build pipelines, where error-level rules are enforced.

You can use Vale:

On the command line.
In a code editor.
In a Git hook. Vale only reports errors in the Git hook (the same configuration as the CI/CD pipelines), and does not report suggestions or warnings.

Vale result types

Vale returns three types of results: suggestion, warning, and error:

Suggestion-level results are writing tips and aren't displayed in CI job output. Suggestions don't break CI. See a list of suggestion-level rules.
Warning-level results are Style Guide violations, aren't displayed in CI job output, and should contain clear explanations of how to resolve the warning. Warnings may be technical debt, or can be future error-level test items (after the Technical Writing team completes its cleanup). Warnings don't break CI. See a list of warning-level rules.
Error-level results are Style Guide violations, and should contain clear explanations of how to resolve the error. Errors break CI and are displayed in CI job output. See a list of error-level rules.

Vale spelling test

When Vale flags a valid word as a spelling mistake, you can fix it following these guidelines:

Flagged word	Guideline
jargon	Rewrite the sentence to avoid it.
correctly-capitalized name of a product or service	Add the word to the vale spelling exceptions list.
name of a person	Remove the name if it's not needed, or add the vale exception code in-line.
a command, variable, code, or similar	Put it in backticks or a code block. For example: `The git clone command can be used with the CI_COMMIT_BRANCH variable.` -> The `git clone` command can be used with the `CI_COMMIT_BRANCH` variable.
UI text from GitLab	Verify it correctly matches the UI, then: If it does not match the UI, update it. If it matches the UI, but the UI seems incorrect, create an issue to see if the UI needs to be fixed. If it matches the UI and seems correct, add it to the vale spelling exceptions list.
UI text from a third-party product	Rewrite the sentence to avoid it, or add the vale exception code in-line.

Vale readability score

In ReadingLevel.yml, we have implemented the Flesch-Kincaid grade level test to determine the readability of our documentation.

As a general guideline, the lower the score, the more readable the documentation. For example, a page that scores 12 before a set of changes, and 9 after, indicates an iterative improvement to readability. The score is not an exact science, but is meant to help indicate the general complexity level of the page.

The readability score is calculated by using the following formula:

(.39 x ASL) + (11.8 x ASW) – 15.59

ASL is average sentence length (the number of words divided by the number of sentences).
ASW is the average number of syllables per word (the number of syllables divided by the number of words).
The score excludes headings, code blocks, and lists.

Install linters

At a minimum, install markdownlint and Vale to match the checks run in build pipelines:

Install markdownlint-cli:
```
yarn global add markdownlint-cli
```
We recommend installing the version of markdownlint-cli used (see variables: section) when building the image:docs-lint-markdown.
Install vale. For example, to install using brew for macOS, run:
```
brew install vale
```

These tools can be integrated with your code editor.

Update linters

It's important to use linter versions that are the same or newer than those run in CI/CD. This provides access to new features and possible bug fixes.

To match the versions of markdownlint-cli and vale used in the GitLab projects, refer to the versions used (see variables: section) when building the image:docs-lint-markdown Docker image containing these tools for CI/CD.

Tool	Version	Command	Additional information
`markdownlint-cli`	Latest	`yarn global add markdownlint-cli`	n/a
`markdownlint-cli`	Specific	`yarn global add markdownlint-cli@0.23.2`	The `@` indicates a specific version, and this example updates the tool to version `0.23.2`.
Vale	Latest	`brew update && brew upgrade vale`	This command is for macOS only.
Vale	Specific	n/a	Not possible using `brew`, but can be directly downloaded.

Configure editors

Using linters in your editor is more convenient than having to run the commands from the command line.

To configure markdownlint in your editor, install one of the following as appropriate:

Sublime Text SublimeLinter-contrib-markdownlint package.
Visual Studio Code DavidAnson.vscode-markdownlint extension.
Atom linter-node-markdownlint package.
Vim ALE plugin.

To configure Vale in your editor, install one of the following as appropriate:

Sublime Text SublimeLinter-contrib-vale package.
Visual Studio Code errata-ai.vale-server extension. You can configure the plugin to display only a subset of alerts.

In the extension's settings:
- Select the Use CLI checkbox.
- In the Config setting, enter an absolute path to .vale.ini in one of the cloned GitLab repositories on your computer.
- In the Path setting, enter the absolute path to the Vale binary. In most cases, vale should work. To find the location, run which vale in a terminal.
Vim ALE plugin.

Emacs Flycheck extension. This requires some configuration:

Flycheck supports markdownlint-cli out of the box, but you must point it to the .markdownlint.yml at the base of the project directory. A .dir-locals.el file can accomplish this:

;; Place this code in a file called `.dir-locals.el` at the root of the gitlab project.
((markdown-mode . ((flycheck-markdown-markdownlint-cli-config . ".markdownlint.yml"))))

A minimal configuration for Flycheck to work with Vale could look like this:

(flycheck-define-checker vale
  "A checker for prose"
  :command ("vale" "--output" "line" "--no-wrap"
            source)
  :standard-input nil
  :error-patterns
    ((error line-start (file-name) ":" line ":" column ":" (id (one-or-more (not (any ":")))) ":" (message)   line-end))
  :modes (markdown-mode org-mode text-mode)
  :next-checkers ((t . markdown-markdownlint-cli))
)

(add-to-list 'flycheck-checkers 'vale)

In this setup the markdownlint checker is set as a "next" checker from the defined vale checker. Enabling this custom Vale checker provides error linting from both Vale and markdownlint.

We don't use Vale Server.

Configure pre-push hooks

Git pre-push hooks allow Git users to:

Run tests or other processes before pushing a branch.
Avoid pushing a branch if failures occur with these tests.

lefthook is a Git hooks manager, making configuring, installing, and removing Git hooks easy.

Configuration for lefthook is available in the lefthook.yml file for the gitlab project.

To set up lefthook for documentation linting, see Pre-push static analysis.

Show subset of Vale alerts

You can set Visual Studio Code to display only a subset of Vale alerts when viewing files:

Go to Preferences > Settings > Extensions > Vale.
In Vale CLI: Min Alert Level, select the minimum alert level you want displayed in files.

To display only a subset of Vale alerts when running Vale from the command line, use the --minAlertLevel flag, which accepts error, warning, or suggestion. Combine it with --config to point to the configuration file within the project, if needed:

vale --config .vale.ini --minAlertLevel error doc/**/*.md

Omit the flag to display all alerts, including suggestion level alerts.

Disable Vale tests

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  tag before the text, and a  tag after the text, replacing rulename with the filename of a test in the GitLab styles directory.
To disable all Vale linting rules, add a  tag before the text, and a  tag after the text.

Whenever possible, exclude only the problematic rule and lines.

For more information, see Vale's documentation.

Disable markdownlint tests

To disable all markdownlint rules, add a  tag before the text, and a  tag after the text.

To disable only a specific rule, add the rule number to the tag, for example  and .

Whenever possible, exclude only the problematic lines.

19 KiB Raw Blame History Unescape Escape