diff options
Diffstat (limited to 'doc/development/documentation/structure.md')
| -rw-r--r-- | doc/development/documentation/structure.md | 398 |
1 files changed, 7 insertions, 391 deletions
diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index a5d1290a17a..35a93f08f66 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -1,395 +1,11 @@ --- -stage: none -group: Style Guide -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/#assignments -description: What to include in GitLab documentation pages. +redirect_to: 'topic_types/index.md' +remove_date: '2022-11-16' --- -# Documentation topic types (CTRT) +This document was moved to [another location](topic_types/index.md). -At GitLab, we have not traditionally used types for our content. However, we are starting to -move in this direction, and we now use four primary topic types (CTRT): - -- [Concept](#concept) -- [Task](#task) -- [Reference](#reference) -- [Troubleshooting](#troubleshooting) - -In general, each page in our docset contains multiple topics. (Each heading indicates a new topic.) -Each topic on a page should be a specific topic type. For example, -a page with the title `Pipelines` can include topics that are concepts and tasks. - -A page might also contain only one type of information. These pages are generally one of our -[other content types](#other-types-of-content). - -## Concept - -A concept introduces a single feature or concept. - -A concept should answer the questions: - -- What is this? -- Why would I use it? - -Think of everything someone might want to know if they've never heard of this concept before. - -Don't tell them **how** to do this thing. Tell them **what it is**. - -If you start describing another concept, start a new concept and link to it. - -Concepts should be in this format: - -```markdown -# Title (a noun, like "Widgets") - -A paragraph that explains what this thing is. - -Another paragraph that explains what this thing is. - -Remember, if you start to describe about another concept, stop yourself. -Each concept should be about one concept only. -``` - -### Concept headings - -For the heading 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: - -- `Overview` or `Introduction`. Instead, use a more specific - noun or phrase that someone would search for. -- `Use cases`. Instead, incorporate the information as part of the concept. -- `How it works`. Instead, use a noun followed by `workflow`. For example, `Merge request workflow`. - -## Task - -A task gives instructions for how to complete a procedure. - -Tasks should be in this format: - -```markdown -# Title (starts with an active verb, like "Create a widget" or "Delete a widget") - -Do this task when you want to... - -Prerequisites (optional): - -- Thing 1 -- Thing 2 -- Thing 3 - -To do this task: - -1. Location then action. (Go to this menu, then select this item.) -1. Another step. -1. Another step. - -Task result (optional). Next steps (optional). -``` - -Here is an example. - -```markdown -# Create an issue - -Create an issue when you want to track bugs or future work. - -Prerequisites: - -- You must have at least the Developer role for the project. - -To create an issue: - -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Issues > List**. -1. In the top right corner, select **New issue**. -1. Complete the fields. (If you have reference content that lists each field, link to it here.) -1. Select **Create issue**. - -The issue is created. You can view it by going to **Issues > List**. -``` - -### Task headings - -For the heading 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 -`Prerequisites` and link to it. - -## Reference - -Reference information should be in an easily-scannable format, -like a table or list. It's similar to a dictionary or encyclopedia entry. - -```markdown -# Title (a noun, like "Pipeline settings" or "Administrator options") - -Introductory sentence. - -| Setting | Description | -|---------|-------------| -| **Name** | Descriptive sentence about the setting. | -``` - -### Reference headings - -Reference headings are usually nouns. - -Avoid these heading titles: - -- `Important notes`. Instead, incorporate this information - closer to where it belongs. For example, this information might be a prerequisite - for a task, or information about a concept. -- `Limitations`. Instead, move the content near other similar information. - If you must, you can use the title `Known issues`. - -## Troubleshooting - -Troubleshooting topics should be the last topics on a page. - -Troubleshooting can be one of three categories: - -- **An introductory topic.** This topic introduces the troubleshooting section of a page. - For example: - - ```markdown - ## Troubleshooting - - When working with <x feature>, you might encounter the following issues. - ``` - -- **Troubleshooting task.** The title should be similar to a [standard task](#task). - For example, "Run debug tools" or "Verify syntax." - -- **Troubleshooting reference.** This information includes the error message. For example: - - ```markdown - ### The error message or a description of it - - You might get an error that states <error message>. - - This issue occurs when... - - 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. - -If a page has more than five troubleshooting topics, put the content on a separate page that has troubleshooting information exclusively. Name the page `Troubleshooting <featurename>`. - -### Troubleshooting headings - -For the heading of a **Troubleshooting reference** topic: - -- Consider including at least a partial error message. -- Use fewer than 70 characters. - -If you do not put the full error in the title, include it in the body text. - -### Related topics - -If inline links are not sufficient, you can create a topic called **Related topics** -and include an unordered list of related topics. This topic should be above the Troubleshooting section. - -```markdown -# Related topics - -- [Configure your pipeline](link-to-topic) -- [Trigger a pipeline manually](link-to-topic) -``` - -## General heading text guidelines - -In general, for heading 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, - instead of `Troubleshooting merge requests`, use only `Troubleshooting`. - -See also [guidelines for headings in Markdown](styleguide/index.md#headings-in-markdown). - -## Other types of content - -There are other types of content in the GitLab documentation that don't -classify as one of the four primary [topic types](#documentation-topic-types-ctrt). -These include: - -- [Tutorials](#tutorials) -- [Get started pages](#get-started) -- [Topics and resources pages](#topics-and-resources-pages) - -In most cases, these pages are standalone. - -### Tutorials - -A tutorial is an end-to-end walkthrough of a complex workflow or scenario. -In general, you might consider using a tutorial when: - -- The workflow requires a number of sequential steps where each step consists - of sub-steps. -- The steps cover a variety of GitLab features or third-party tools. - -Tutorials are learning aids that complement our core documentation. -They do not introduce new features. -Always use the primary [topic types](#documentation-topic-types-ctrt) to document new features. - -Tutorials should be in this format: - -```markdown -# Title (starts with "Tutorial:" followed by an active verb, like "Tutorial: Create a website") - -A paragraph that explains what the tutorial does, and the expected outcome. - -To create a website: - -1. [Do the first task](#do-the-first-task) -1. [Do the second task](#do-the-second-task) - -Prerequisites (optional): - -- Thing 1 -- Thing 2 -- Thing 3 - -## Do the first task - -To do step 1: - -1. First step. -1. Another step. -1. Another step. - -## Do the second task - -Before you begin, make sure you have [done the first task](#do-the-first-task). - -To do step 2: - -1. First step. -1. Another step. -1. Another step. -``` - -### Get started - -A get started page is a set of steps to help a user get set up -quickly to use a single GitLab feature or tool. -It might consist of more than one task. - -Get started pages should be in this format: - -```markdown -# Title ("Get started with <feature>") - -Complete the following steps to ... . - -1. First step. -1. Another step. -1. Another step. - -If you need to add more than one task, -consider using subsections for each distinct task. -``` - -### Topics and resources pages - -This page has a list of links that point to important sections -of documentation for a specific GitLab feature or tool. - -We do not encourage the use of these types of pages. -Lists like this can get out of date quickly and offer little value to users. -We've included this type here because: - -- There are existing pages in the documentation that follow this format, - and they should be standardized. -- They can sometimes help navigate a complex section of the documentation. - -If you come across a page like this -or you have to create one, use this format: - -```markdown -# Title ("Topics and resources for <feature>") - -Brief sentence to describe the feature. - -Refer to these resources for more information about <this feature>: - -- Link 1 -- Link 2 -- Link 3 -``` - -## Help and feedback section - -This section ([introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/319) in GitLab 11.4) -is displayed at the end of each document and can be omitted by adding a key into -the front matter: - -```yaml ---- -feedback: false ---- -``` - -The default is to leave it there. If you want to omit it from a document, you -must check with a technical writer before doing so. - -### Disqus - -We also have integrated the docs site with Disqus (introduced by -[!151](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/151)), -allowing our users to post comments. - -To omit only the comments from the feedback section, use the following key in -the front matter: - -```yaml ---- -comments: false ---- -``` - -We're hiding comments only in main index pages, such as [the main documentation index](../../index.md), -since its content is too broad to comment on. Before omitting Disqus, you must -check with a technical writer. - -Note that after adding `feedback: false` to the front matter, it will omit -Disqus, therefore, don't add both keys to the same document. - -The click events in the feedback section are tracked with Google Tag Manager. -The conversions can be viewed on Google Analytics by navigating to -**Behavior > Events > Top events > docs**. - -## Guidelines for good practices - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36576/) in GitLab 13.2 as GitLab Development documentation. - -*Good practice* examples demonstrate encouraged ways of writing code while -comparing with examples of practices to avoid. These examples are labeled as -*Bad* or *Good*. In GitLab development guidelines, when presenting the cases, -it's recommended to follow a *first-bad-then-good* strategy. First demonstrate -the *Bad* practice (how things *could* be done, which is often still working -code), and then how things *should* be done better, using a *Good* example. This -is typically an improved example of the same code. - -Consider the following guidelines when offering examples: - -- First, offer the *Bad* example, and then the *Good* one. -- When only one bad case and one good case is given, use the same code block. -- When more than one bad case or one good case is offered, use separated code - blocks for each. With many examples being presented, a clear separation helps - the reader to go directly to the good part. Consider offering an explanation - (for example, a comment, or a link to a resource) on why something is bad - practice. -- Better and best cases can be considered part of the good cases' code block. - In the same code block, precede each with comments: `# Better` and `# Best`. - -Although the bad-then-good approach is acceptable for the GitLab development -guidelines, do not use it for user documentation. For user documentation, use -*Do* and *Don't*. For examples, see the [Pajamas Design System](https://design.gitlab.com/content/punctuation/). +<!-- This redirect file can be deleted after <2022-11-16>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file |