Commit c3691f24 authored by Craig Norris's avatar Craig Norris

Merge branch 'selhorn-introduce-examples' into 'master'

Added guidance for introducing examples

See merge request gitlab-org/gitlab!50232
parents faac2f85 60b72c88
......@@ -22,7 +22,7 @@ You can also view a list of [recent updates to this guide](https://gitlab.com/da
If you can't find what you need:
- View the GitLab Handbook for [writing style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) that apply to all GitLab content.
- Refer to one of the following:
- Refer to:
- [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/).
- [Google Developer Documentation Style Guide](https://developers.google.com/style).
......@@ -161,7 +161,7 @@ Markdown rendering engine. For a complete Kramdown reference, see the
The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown) Ruby gem
plans to support all [GitLab Flavored Markdown](../../../user/markdown.md) in the future, which is
all Markdown supported for display in the GitLab application itself. For now, use
regular Markdown, following the rules in the linked style guide.
regular Markdown and follow the rules in the linked style guide.
Kramdown-specific markup (for example, `{:.class}`) doesn't render
properly on GitLab instances under [`/help`](../index.md#gitlab-help).
......@@ -252,7 +252,7 @@ Put files for a specific product area into the related folder:
### Work with directories and files
Refer to the following items when working with directories and files:
When working with directories and files:
1. When you create a new directory, always start with an `index.md` file.
Don't use another filename and _do not_ create `README.md` files.
......@@ -412,7 +412,7 @@ references to user interface elements. For example:
### Inclusive language
We strive to create documentation that's inclusive. This section includes
guidance and examples for the following categories:
guidance and examples for these categories:
- [Gender-specific wording](#avoid-gender-specific-wording).
(Tested in [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml).)
......@@ -481,7 +481,7 @@ more precise and functional, such as `primary` and `secondary`.
<!-- vale gitlab.InclusionCultural = YES -->
For more information see the following [Internet Draft specification](https://tools.ietf.org/html/draft-knodel-terminology-02).
For more information see the [Internet Draft specification](https://tools.ietf.org/html/draft-knodel-terminology-02).
### Fake user information
......@@ -507,7 +507,7 @@ There may be times where a token is needed to demonstrate an API call using
cURL or a variable used in CI. It is strongly advised not to use real tokens in
documentation even if the probability of a token being exploited is low.
You can use the following fake tokens as examples:
You can use these fake tokens as examples:
| Token type | Token value |
|:----------------------|:-------------------------------------------------------------------|
......@@ -527,9 +527,11 @@ You can use the following fake tokens as examples:
<!-- vale off -->
| Usage | Guidance |
|-----------------------|-----|
|-----------------------|----------|
| above | Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **previously** instead. |
| admin, admin area | Use **administration**, **administrator**, **administer**, or **Admin Area** instead. |
| and/or | Use **or** instead, or another sensible construction. |
| below | Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **following** instead. |
| currently | Do not use when talking about the product or its features. The documentation describes the product as it is today. |
| easily | Do not use. If the user doesn't find the process to be these things, we lose their trust. |
| e.g. | Do not use Latin abbreviations. Use **for example**, **such as**, **for instance**, or **like** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) |
......@@ -865,7 +867,7 @@ Consider installing a plugin or extension in your editor for formatting tables:
When creating tables of lists of features (such the features
available to each role on the [Permissions](../../../user/permissions.md#project-members-permissions)
page), use the following phrases:
page), use these phrases:
| Option | Markdown | Displayed result |
|--------|--------------------------|------------------------|
......@@ -967,7 +969,7 @@ Links are important in GitLab documentation. They allow you to [link instead of
summarizing](#link-instead-of-summarize) to help preserve a [single source of truth](#why-a-single-source-of-truth)
in GitLab documentation.
We include guidance for links in the following categories:
We include guidance for links in these categories:
- How to set up [anchor links](#anchor-links) for headings.
- How to set up [criteria](#basic-link-criteria) for configuring a link.
......@@ -1144,7 +1146,7 @@ When documenting navigation through the user interface:
### Navigational elements
Use the following terms when referring to the main GitLab user interface
Use these terms when referring to the main GitLab user interface
elements:
- **Top menu**: This is the top menu that spans the width of the user interface.
......@@ -1183,7 +1185,7 @@ When you take screenshots:
- Save the image with a lowercase filename that's descriptive of the feature
or concept in the image. If the image is of the GitLab interface, append the
GitLab version to the filename, based on the following format:
GitLab version to the filename, based on this 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
......@@ -1365,7 +1367,7 @@ hidden on the documentation site, but is displayed by `/help`.
<!-- vale on -->
Syntax highlighting is required for fenced code blocks added to the GitLab
documentation. Refer to the following table for the most common language classes,
documentation. Refer to this table for the most common language classes,
or check the [complete list](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers)
of available language classes:
......@@ -1433,7 +1435,7 @@ Usage examples:
Icons should be used sparingly, and only in ways that aid and do not hinder the
readability of the text.
For example, the following adds little to the accompanying text:
For example, this Markdown adds little to the accompanying text:
```markdown
1. Go to **{home}** **Project overview > Details**.
......@@ -1441,7 +1443,7 @@ For example, the following adds little to the accompanying text:
1. Go to **{home}** **Project overview > Details**.
However, the following might help the reader connect the text to the user
However, these tables might help the reader connect the text to the user
interface:
```markdown
......@@ -1555,14 +1557,12 @@ It renders on the GitLab documentation site as:
## Terms
To maintain consistency through GitLab documentation, the following guides
documentation authors on agreed styles and usage of terms.
To maintain consistency through GitLab documentation, use these styles and terms.
### Merge requests (MRs)
Merge requests allow you to exchange changes you made to source code and
collaborate with other people on the same project. This term is used in
the following ways:
collaborate with other people on the same project.
- Use lowercase _merge requests_ regardless of whether referring to the feature
or individual merge requests.
......@@ -1580,7 +1580,7 @@ Examples:
### Describe UI elements
The following are styles to follow when describing user interface elements in an
Follow these styles when you're describing user interface elements in an
application:
- For elements with a visible label, use that label in bold with matching case.
......@@ -1590,7 +1590,7 @@ application:
### Verbs for UI elements
The following are recommended verbs for specific uses with user interface
Use these verbs for specific uses with user interface
elements:
| Recommended | Used for | Replaces |
......@@ -1637,7 +1637,7 @@ displayed for the page or feature.
#### Version text in the **Version History**
If all content in a section is related, add version text following the header
If all content in a section is related, add version text after the header
for the section. The version information must be surrounded by blank lines, and
each entry should be on its own line.
......@@ -1709,7 +1709,7 @@ voters to agree.
#### End-of-life for features or products
When a feature or product enters its end-of-life, indicate its status by
creating a [warning alert](#alert-boxes) directly following its relevant header.
creating a [warning alert](#alert-boxes) directly after its relevant header.
If possible, link to its deprecation and removal issues.
For example:
......
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