diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index f6ed4cdcaa9e08856887ea374faf589294d81982..7e83eee27608bcd0b4c08ed8ecce4420c678b396 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -170,26 +170,17 @@ Hard-coded HTML is valid, although it's discouraged from being used. HTML is per - Special styling is required. - Reviewed and approved by a technical writer. -### Headings in Markdown +### Heading levels in Markdown Each documentation page begins with a level 1 heading (`#`). This becomes the `h1` element when the page is rendered to HTML. There can be only **one** level 1 heading per page. - For each subsection, increment the heading level. In other words, increment the number of `#` characters - in front of the heading. -- Avoid headings greater than `H5` (`#####`). If you need more than five heading levels, move the topics to a new page instead. - Headings greater than `H5` do not display in the right sidebar navigation. + in front of the topic title. +- Avoid heading levels greater than `H5` (`#####`). If you need more than five heading levels, move the topics to a new page instead. + Heading levels greater than `H5` do not display in the right sidebar navigation. - Do not skip a level. For example: `##` > `####`. -- Leave one blank line before and after the heading. - -When you change heading text, the anchor link changes. To avoid broken links: - -- Do not use step numbers in headings. -- When possible, do not use words that might change in the future. - -Also, do not use links as part of heading text. - -See also [heading guidelines for specific topic types](../structure.md). +- Leave one blank line before and after the topic title. ### Backticks in Markdown @@ -248,9 +239,9 @@ GitLab documentation should be clear and easy to understand. As a company, we tend toward lowercase. -#### Headings +#### Topic titles -Use sentence case. For example: +Use sentence case for topic titles. For example: - `# Use variables to configure pipelines` - `## Use the To-Do List` @@ -356,7 +347,7 @@ Some contractions, however, should be avoided: ### Acronyms If you use an acronym, spell it out on first use on a page. You do not need to spell it out more than once on a page. -When possible, try to avoid acronyms in headings. +When possible, try to avoid acronyms in topic titles. ### Numbers @@ -713,22 +704,27 @@ use a URL like `https://docs.gitlab.com/charts/`. ### Anchor links -Each heading has an anchor link. For example, a topic with the title +Each topic title has an anchor link. For example, a topic with the title `## This is an example` has the anchor `#this-is-an-example`. -The first topic on a page (the `h1`) has an anchor link, +The first topic title on a page (the `h1`) has an anchor link, but do not use it. Link to the page instead. -If a heading has a [product tier badge](#product-tier-badges), -do not include it in the anchor link. For example, for the heading +If a topic title has a [product tier badge](#product-tier-badges), +do not include it in the anchor link. For example, for the topic `## This is an example **(FREE)**`, use the anchor `#this-is-an-example`. With Kramdown, you can add a custom ID to an HTML element, but these IDs don't work in `/help`, so you should not use them. +When you change topic title text, the anchor link changes. To avoid broken links: + +- Do not use step numbers in topic titles. +- When possible, do not use words that might change in the future. + #### Changing links and titles -When you change a heading, the anchor link changes. To ensure you update +When you change a topic title, the anchor link changes. To ensure you update any related links, search these directories: - `doc/*` @@ -1231,7 +1227,7 @@ Instead of adding a note: - Re-write the sentence as part of a paragraph. - Put the information into its own paragraph. -- Put the content under a new subheading. +- Put the content under a new topic title. If you must use a note, use this format: @@ -1416,25 +1412,25 @@ When names change, it is more complicated to search or grep text that has line b ### Product tier badges -Tier badges are displayed as orange text next to a heading. These badges link to the GitLab +Tier badges are displayed as orange text next to a topic title. These badges link to the GitLab pricing page. For example:  You must assign a tier badge: -- To all H1 topic headings, except the pages under `doc/development/*`. -- To topic headings that don't apply to the same tier as the H1. +- To all H1 topic titles, except the pages under `doc/development/*`. +- To topic titles that don't apply to the same tier as the H1. -To add a tier badge to a heading, add the relevant tier badge -after the heading text. For example: +To add a tier badge to a topic title, add the relevant tier badge +after the title text. For example: ```markdown -# Heading title **(FREE)** +# Topic title **(FREE)** ``` Do not add tier badges inline with other text, except for [API attributes](../restful_api_styleguide.md). -The single source of truth for a feature should be the heading where the +The single source of truth for a feature should be the topic where the functionality is described. #### Available product tier badges diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 6f51096ee5665de3deb16c4ab393fe1af717dcbf..faac229d8d3afe1b36681ba708c351bb6fb712d1 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -35,7 +35,7 @@ Don't use backticks. ## 2FA, two-factor authentication -Spell out **two-factor authentication** in sentence case for the first use and in section headings, and **2FA** +Spell out **two-factor authentication** in sentence case for the first use and in topic titles, and **2FA** thereafter. If the first word in a sentence, do not capitalize `factor` or `authentication`. For example: - Two-factor authentication (2FA) helps secure your account. Set up 2FA when you first log in. diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index c801bb9f8770336294c105e83b56582024cbe60c..8b8f281d7c16274e8cb300338dc20e238d530668 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -86,7 +86,7 @@ job, which runs two types of link checks. In both cases, links with destinations that begin with `http` or `https` are considered external links, and skipped: - `bundle exec nanoc check internal_links`: Tests links to internal pages. -- `bundle exec nanoc check internal_anchors`: Tests links to subheadings (anchors) on internal pages. +- `bundle exec nanoc check internal_anchors`: Tests links to topic title anchors on internal pages. Failures from these tests are displayed at the end of the test results in the **Issues found!** area. For example, failures in the `internal_anchors` test follow this format: @@ -104,7 +104,7 @@ For example, failures in the `internal_anchors` test follow this format: - **Destination**: The full path to the file not found by the test. To find the file in the `gitlab` repository, replace `/tmp/gitlab-docs/public/ee` with `doc`, and `.html` with `.md`. - **Link**: The actual link the script attempted to find. -- **Anchor**: If present, the subheading (anchor) the script attempted to find. +- **Anchor**: If present, the topic title anchor the script attempted to find. Check for multiple instances of the same broken link on each page reporting an error. Even if a specific broken link appears multiple times on a page, the test reports it only once. diff --git a/doc/development/documentation/topic_types/concept.md b/doc/development/documentation/topic_types/concept.md index dfd003b642d5d6028eb79c7fa4e56bc4fbe08f03..7be6bef4fadaae48693b8e7944debfc8aff1d1a6 100644 --- a/doc/development/documentation/topic_types/concept.md +++ b/doc/development/documentation/topic_types/concept.md @@ -32,13 +32,13 @@ Remember, if you start to describe about another concept, stop yourself. Each concept should be about one concept only. ``` -## Concept headings +## Concept topic titles -For the heading text, use a noun. For example, `Widgets` or `GDK dependency management`. +For the title text, use a noun. For example, `Widgets` or `GDK dependency management`. If a noun is ambiguous, you can add a gerund. For example, `Documenting versions` instead of `Versions`. -Avoid these heading titles: +Avoid these topic titles: - `Overview` or `Introduction`. Instead, use a more specific noun or phrase that someone would search for. diff --git a/doc/development/documentation/topic_types/index.md b/doc/development/documentation/topic_types/index.md index d88a5448d53173e0aad8d7c766c91f2ae70635c7..8e8c474ce3cca88bf6b5847985544aa939ecda58 100644 --- a/doc/development/documentation/topic_types/index.md +++ b/doc/development/documentation/topic_types/index.md @@ -66,14 +66,14 @@ Some pages are solely a list of links to other documentation. We do not encourage this page type. Lists of links can get out-of-date quickly and offer little value to users, who prefer to search to find information. -## Heading text guidelines +## Topic text guidelines -In general, for heading text: +In general, for topic text: - Be clear and direct. Make every word count. - Use articles and prepositions. - Follow [capitalization](../styleguide/index.md#capitalization) guidelines. -- Do not repeat text from earlier headings. For example, if the page is about merge requests, +- Do not repeat text from earlier topic titles. For example, if the page is about merge requests, instead of `Troubleshooting merge requests`, use only `Troubleshooting`. -See also [guidelines for headings in Markdown](../styleguide/index.md#headings-in-markdown). +See also [guidelines for heading levels in Markdown](../styleguide/index.md#heading-levels-in-markdown). diff --git a/doc/development/documentation/topic_types/reference.md b/doc/development/documentation/topic_types/reference.md index e7ee8b20925938503e6daf0032a012a78dd0a5fd..8bb89f4c2108a8ed26107a7192747f01f6cb2a87 100644 --- a/doc/development/documentation/topic_types/reference.md +++ b/doc/development/documentation/topic_types/reference.md @@ -19,11 +19,11 @@ Introductory sentence. | **Name** | Descriptive sentence about the setting. | ``` -## Reference headings +## Reference topic titles -Reference headings are usually nouns. +Reference topic titles are usually nouns. -Avoid these heading titles: +Avoid these topic titles: - `Important notes`. Instead, incorporate this information closer to where it belongs. For example, this information might be a prerequisite diff --git a/doc/development/documentation/topic_types/task.md b/doc/development/documentation/topic_types/task.md index 6e6213b000bde93b3dbdc4651384f0d5ed012662..78d670a16d600ade196f12fd0171a4b8e4fcfd21 100644 --- a/doc/development/documentation/topic_types/task.md +++ b/doc/development/documentation/topic_types/task.md @@ -52,9 +52,9 @@ To create an issue: The issue is created. You can view it by going to **Issues > List**. ``` -## Task headings +## Task topic titles -For the heading text, use the structure `active verb` + `noun`. +For the title text, use the structure `active verb` + `noun`. For example, `Create an issue`. If you have several tasks on a page that share prerequisites, you can use the title diff --git a/doc/development/documentation/topic_types/troubleshooting.md b/doc/development/documentation/topic_types/troubleshooting.md index 0fb36554995ee1c41cec82c97b50b95b411b8679..70475eb0ccf10220d48b6e76938ad0f2298850a5 100644 --- a/doc/development/documentation/topic_types/troubleshooting.md +++ b/doc/development/documentation/topic_types/troubleshooting.md @@ -46,12 +46,13 @@ The workaround is... If multiple causes or workarounds exist, consider putting them into a table format. If you use the exact error message, surround it in backticks so it's styled as code. -## Troubleshooting headings +## Troubleshooting topic titles -For the heading of a **Troubleshooting reference** topic: +For the title of a **Troubleshooting reference** topic: - Consider including at least a partial error message. - Use fewer than 70 characters. +- Do not use links in the title. If you do not put the full error in the title, include it in the body text. diff --git a/doc/development/documentation/topic_types/tutorial.md b/doc/development/documentation/topic_types/tutorial.md index 0164b525528216e7a64168e2ee6f72200830fb39..4c8e9e4c5adc34ee9fd204b74bee4bc4bff16f19 100644 --- a/doc/development/documentation/topic_types/tutorial.md +++ b/doc/development/documentation/topic_types/tutorial.md @@ -54,9 +54,9 @@ To do step 2: 1. Another step. ``` -## Tutorial headings +## Tutorial page title -Start with `Tutorial:` followed by an active verb, like `Tutorial: Create a website`. +Start the page title with `Tutorial:` followed by an active verb, like `Tutorial: Create a website`. ## Screenshots diff --git a/doc/development/documentation/versions.md b/doc/development/documentation/versions.md index 12381b84c2cce4f4e81208ebb3383c4e3545cc5f..030bdec036121775e213e10e8f92e9b164d543c0 100644 --- a/doc/development/documentation/versions.md +++ b/doc/development/documentation/versions.md @@ -31,7 +31,7 @@ You do not need to add version information on the pages in the `/development` di ### Add a **Version history** item -If all content in a topic is related, add a version history item after the topic heading. +If all content in a topic is related, add a version history item after the topic title. For example: ```markdown diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 85d3d5e9cfc5b7e94064021093ecdb3d67d78068..9d8d25607c81a8ff423135e012d90bebdd3bf2bc 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -153,7 +153,7 @@ Ensure the following if skipping an initial Technical Writer review: - [Product badges](styleguide/index.md#product-tier-badges) are applied. - The GitLab [version](versions.md) that introduced the feature is included. -- Changes to headings don't affect in-app hyperlinks. +- Changes to topic titles don't affect in-app hyperlinks. - Specific [user permissions](../../user/permissions.md) are documented. - New documents are linked from higher-level indexes, for discoverability. - The style guide is followed: