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. +- **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). -For additional details, see the subsections below, as well as the [Documentation template for new docs](#Documentation-template-for-new-docs). +For additional details on each, see the [template for new docs](#template-for-new-docs), +below. -### Feature overview and use cases +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. -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: - -- 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 (`