kotovalexarian-likes-gitlab/gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity

Further refinements to the page

Browse source
This commit is contained in:
Mike Lewis 2018-12-31 18:04:46 +00:00
parent 1d78b3ba4d
commit 9bde1e910f
1 changed files with 25 additions and 62 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

87
doc/development/documentation/structure.md
View file

@ -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 (`<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
Your new document will be discoverable by the user only if:
- 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. -->
---