diff options
Diffstat (limited to 'doc/development/documentation/structure.md')
| -rw-r--r-- | doc/development/documentation/structure.md | 87 |
1 files changed, 25 insertions, 62 deletions
diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index 54534ca3134..f10b7205a86 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -16,72 +16,24 @@ and the section on Content in the [Style Guide](styleguide.md). Most pages will be dedicated to a specifig GitLab feature or to a use case that involves one or more features and/or third-party tools. -Every feature or use case document should include the following content in the following sequence.: +Every feature or use case document should include the following content in the following sequence: - **Title**: Top-level heading with the feature name, or a use case name, which would start with a verb, like Configuring, Enabling, etc. - **Introduction**: A couple sentences about the subject matter and what's to be found on this page. - **Overview** Describe what it is, what it does, and in what context it should be used. - **Use cases**: describes real use case scenarios for that feature/configuration. -- **Requirements**: describes what software and/or configuration is required to be able to - use the feature and, if applicable, prerequisite knowledge for being able to follow/implement the tutorial. - For example, familiarity with GitLab CI/CD, an account on a third-party service, dependencies installed, etc. - Link each one to its most relevant resource; i.e., where the reader can go to begin to fullfil that requirement. - (Another doc page, a third party application's site, etc.) -- **Instructions**: clearly describes the steps to follow, leaving no gaps. -- **Troubleshooting** guide (recommended but not required): if you know beforehand what issues - one might have when setting it 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 in the - docs. This is important to minimize requests for support, and to avoid doc comments with - questions that you know someone might ask. Answering them beforehand only makes your - document better and more approachable. - -For additional details, see the subsections below, as well as the [Documentation template for new docs](#Documentation-template-for-new-docs). - -### Feature overview and use cases - -Every major feature (regardless if present in GitLab Community or Enterprise editions) -should present, at the beginning of the document, two main sections: **overview** and -**use cases**. Every GitLab EE-only feature should also contain these sections. - -**Overview**: as the name suggests, the goal here is to provide an overview of the feature. -Describe what it is, what it does, why it is important/cool/nice-to-have, -what problem it solves, and what you can do with this feature that you couldn't -do before. - -**Use cases**: provide at least two, ideally three, use cases for every major feature. -You should answer this question: what can you do with this feature/change? Use cases -are examples of how this feature or change can be used in real life. - -Examples: +- **Requirements**: describes what software, configuration, account, or knowledge is required. +- **Instructions**: One or more sets of detailed instructions to follow. +- **Troubleshooting** guide (recommended but not required). -- 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](https://docs.gitlab.com/ee/administration/geo/replication/index.html) -- EE-only: [Jenkins integration](https://docs.gitlab.com/ee/integration/jenkins.html) - -Note that if you don't have anything to add between the doc title (`<h1>`) and -the header `## Overview`, you can omit the header, but keep the content of the -overview there. - -> **Overview** and **use cases** are required to **every** Enterprise Edition feature, -and for every **major** feature present in Community Edition. - -### Discoverability +For additional details on each, see the [template for new docs](#template-for-new-docs), +below. -Your new document will be discoverable by the user only if: +Note that you can include additional subsections, as appropriate, such as 'How it Works', 'Architecture', +and other logicial divisions such as pre- and post-deployment steps. -- Crosslinked from the higher-level index (e.g., Issue Boards docs - should be linked from Issues; Prometheus docs should be linked from - Monitoring; CI/CD tutorials should be linked from CI/CD examples). - - When referencing other GitLab products and features, link to their - respective docs; when referencing third-party products or technologies, - link out to their external sites, documentation, and resources. -- The headings are clear. E.g., "App testing" is a bad heading, "Testing - an application with GitLab CI/CD" is much better. Think of something - someone will search for and use these keywords in the headings. - -## Documentation template for new docs +## Template for new docs To start a new document, respect the file tree and file name guidelines, as well as the style guidelines. Use the following template: @@ -101,7 +53,7 @@ description: "Short document description." # Up to ~200 chars long. They will be > [Introduced](link_to_issue_or_mr) in GitLab (Tier) X.Y (2). An introduction -- without its own additional header -- goes here. -Offer a short description of the feature or use case, and what to expect on this page. +Offer a very short description of the feature or use case, and what to expect on this page. (You can reuse this content, or part of it, for the front matter's `description` at the top of this file). ## Overview @@ -119,7 +71,13 @@ The feature overview should answer the following questions: Describe some use cases, typically in bulleted form. Include real-life examples for each. If the page itself is dedicated to a use case, this section can usually include more specific scenarios -for use, but if that's not applicable, the section can be omitted. +for use (e.g. variations on the main use case), but if that's not applicable, the section can be omitted. + +Examples of use cases on feature pages: +- 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](https://docs.gitlab.com/ee/administration/geo/replication/index.html) +- EE-only: [Jenkins integration](https://docs.gitlab.com/ee/integration/jenkins.html) ## Requirements @@ -148,10 +106,15 @@ is simple and the document is short. <!-- ## Troubleshooting -Include any troubleshooting steps that you can foresee. -Each scenario can be a third-level heading, e.g. ### Getting error message X +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 doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### 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. --> +but commented out to help encourage others to add to it in the future. --> --- |