diff options
Diffstat (limited to 'doc/development/documentation/structure.md')
| -rw-r--r-- | doc/development/documentation/structure.md | 230 |
1 files changed, 114 insertions, 116 deletions
diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index fd0c29f0fc1..65949d5b5f5 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -5,167 +5,165 @@ info: To determine the technical writer assigned to the Stage/Group associated w description: What to include in GitLab documentation pages. --- -# Documentation structure and template +# Documentation topic types -Use these standards to contribute content to the GitLab documentation. +At GitLab, we have not traditionally used topic types. However, we are starting to +move in this direction, and we now use four topic types: -Before getting started, familiarize yourself with [Documentation guidelines for GitLab](index.md) -and the [Documentation Style Guide](styleguide/index.md). +- [Concept](#concept) +- [Task](#task) +- [Reference](#reference) +- [Troubleshooting](#troubleshooting) -## Components of a documentation page +Each page contains multiple topic types. For example, +a page with the title `Pipelines`, which is generated from a file called `index.md`, +can include a concept and multiple task and reference topics. -Most pages are dedicated to a specific GitLab feature or to a use case that -involves one or more features, potentially in conjunction with third-party tools. +GitLab also uses high-level landing pages. -In general, each topic should include the following content, in this sequence: +## Landing pages -- *Metadata*: Information about the stage, group, and how to find the technical - writer for the topic. This information isn't visible in the published help. -- *Title*: A top-level heading with the feature or use case name. Choose a term - that defines the functionality and use the same term in all the resources - where the feature is mentioned. -- *Introduction*: In a few sentences beneath the title, describe what the - feature or topic is, what it does, and in what context it should be used. -- *Use cases*: Describe real user scenarios. -- *Prerequisites*: Describe the software, configuration, account, permissions, - or knowledge required to use this functionality. -- *Tasks*: Present detailed step-by-step instructions on how to use the feature. -- *Troubleshooting*: List errors and how to address them. Recommended but not - required. +Landing pages are topics that group other topics and help a user to navigate a section. -You can include additional subsections, as appropriate, such as *How it Works*, -or *Architecture*. You can also include other logical divisions, such as -pre-deployment and post-deployment tasks. +Users who are using the in-product help do not have a left nav, +and need these topics to navigate the documentation. -## Template for new docs +These topics can also help other users find the most important topics +in a section. -Follow the [folder structure and filename guidelines](styleguide/index.md#folder-structure-overview) -and create a new topic by using this template: +Landing page topics should be in this format: ```markdown -<!--Follow the Style Guide when working on this document. -https://docs.gitlab.com/ee/development/documentation/styleguide.html -When done, remove all of this commented-out text, except a commented-out -Troubleshooting section, which, if empty, can be left in place to encourage future use.--> ---- -description: "Short document description." # Up to ~200 chars long. This information is 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 -group: Add the group name here -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 ---- +# Title (a noun, like "CI/CD or "Analytics") -# Feature or Use Case Name **[TIER]** (1) -<!--If you are writing about a use case, start with a verb, -for example, "Configure", "Implement", + the goal/scenario--> +Brief introduction to the concept or product area. +Include the reason why someone would use this thing. + +- Bulleted list of important related topics. +- These links are needed because users of in-product help do not have left navigation. +``` -<!--For pages on newly-introduced features, add the following line. -If only some aspects of the feature have been introduced, specify which parts of the feature.--> -> [Introduced](link_to_issue_or_mr) in GitLab (Tier) X.Y (2). +## Concept -Write a description of the feature or use case. This introduction should answer -these questions: +A concept topic introduces a single feature or concept. -- What is this feature or use case? -- Who is it for? -- What is the context in which it is used and are there any prerequisites or - requirements? -- What can the audience do with this? (Be sure to consider all applicable - audiences, such as GitLab admin and developer-user.) -- What are the benefits of using this over any existing alternatives? +A concept should answer the questions: -You can reuse this content, or part of it, for the front matter's `description` -at the top of this file. +- What is this? +- Why would I use it? -## Use cases +Think of everything someone might want to know if they’ve never heard of this topic before. -Describe common use cases, typically in bulleted form. Include real-life examples -for each. +Don’t tell them **how** to do this thing. Tell them **what it is**. -If the page itself is dedicated to a use case, this section usually includes more -specific scenarios for use (for example, variations on the main use case), but if -that's not applicable, you can omit this section. +If you start describing another topic, start a new concept and link to it. + +Concept topics should be in this format: + +```markdown +# Title (a noun, like "Widgets") -Examples of use cases on feature pages: +A paragraph that explains what this thing is. -- CE and EE: [Issues](../../user/project/issues/index.md#use-cases) -- CE and EE: [Merge Requests](../../user/project/merge_requests/index.md) -- EE-only: [Geo](../../administration/geo/index.md) -- EE-only: [Jenkins integration](../../integration/jenkins.md) +Another paragraph that explains what this thing is. -## Prerequisites +Remember, if you start to describe about another concept, stop yourself. +Each concept topic should be about one concept only. +``` -State any prerequisites for using the feature. These might include: +## Task -- Technical prereqs (for example, an account on a third-party service, an amount - of storage space, or prior configuration of another feature) -- Prerequisite knowledge (for example, familiarity with certain GitLab features - or other products and technologies). +A task topic gives instructions for how to complete a procedure. -Link each one to an appropriate place for more information. +Task topics should be in this format: -## Tasks +```markdown +# Title (starts with an active verb, like "Create a widget" or "Delete a widget") -Each topic should help users accomplish a specific task. +Do this task when you want to... -The heading should: +Prerequisites (optional): -- Describe the task and start with a verb. For example, `Create a package` or - `Configure a pipeline`. -- Be short and descriptive (up to ~50 chars). -- Start from an `h2` (`##`), then go over `h3`, `h4`, `h5`, and `h6` as needed. - Never skip a hierarchy level (like `h2` > `h4`). It breaks the table of - contents and can affect the breadcrumbs. +- Thing 1 +- Thing 2 +- Thing 3 -Bigger tasks can have subsections that explain specific phases of the process. +To do this task: -Include example code or configurations when needed. Use Markdown to wrap code -blocks with [syntax highlighting](../../user/markdown.md#colored-code-and-syntax-highlighting). +1. Location then action. (Go to this menu, then select this item.) +1. Another step. +1. Another step. -Example topic: +Task result (optional). Next steps (optional). +``` -## Create a teddy bear +Here is an example. -Create a teddy bear when you need something to hug. (Include the reason why you -might do the task.) +```markdown +# Create an issue -To create a teddy bear: +Create an issue when you want to track bugs or future work. -1. Go to **Settings > CI/CD**. -1. Expand **This** and click **This**. -1. Do another step. +Prerequisites: -The teddy bear is now in the kitchen, in the cupboard above the sink. _(This is the result.)_ +- A minimum of Contributor access to a project in GitLab. -You can retrieve the teddy bear and put it on the couch with the other animals. _(These are next steps.)_ +To create an issue: -Screenshots are not necessary. They are difficult to keep up-to-date and can -clutter the page. +1. Go to **Issues > List**. +1. In the top right, click **New issue**. +1. Complete the fields. (If you have a reference topic that lists each field, link to it here.) +1. Click **Submit issue**. -<!-- ## Troubleshooting +The issue is created. You can view it by going to **Issues > List**. +``` -Include any troubleshooting steps that you can foresee. If you know beforehand -what issues one might have when setting this up, or when something is changed, -or on upgrading, it's important to describe those, too. Think of things that may -go wrong and include them here. This is important to minimize requests for -Support, and to avoid documentation comments with questions that you know -someone might ask. +## Reference -Each scenario can be a third-level heading, for example, `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place but -commented out to help encourage others to add to it in the future. --> +A reference topic provides information 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") -Notes: +Introductory sentence. -- (1): Apply the [tier badges](styleguide/index.md#product-badges) accordingly. -- (2): Apply the correct format for the - [GitLab version that introduces the feature](styleguide/index.md#gitlab-versions-and-tiers). +| Setting | Description | +|---------|-------------| +| **Name** | Descriptive sentence about the setting. | ``` -## Help and feedback section +## Troubleshooting + +Troubleshooting topics can be one of two categories: + +- **Troubleshooting task.** This topic is written the same as a [standard task topic](#task). + For example, "Run debug tools" or "Verify syntax." +- **Troubleshooting reference.** This topic has a specific format. + +Troubleshooting reference topics should be in this format: + +```markdown +# Title (the error message or a description of it) + +You might get an error that states <error message>. + +This issue occurs when... + +The workaround is... +``` + +## Other information on a topic + +Topics include other information. + +For example: + +- Each topic must have a [tier badge](styleguide/index.md#product-tier-badges). +- New topics must have information about the + [GitLab version where the feature was introduced](styleguide/index.md#where-to-put-version-text). + +### 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 @@ -180,7 +178,7 @@ 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 +#### Disqus We also have integrated the docs site with Disqus (introduced by [!151](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/151)), @@ -206,7 +204,7 @@ 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 +### Guidelines for good practices > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36576/) in GitLab 13.2 as GitLab Development documentation. |