Fix links that 404 and style changes
- Some links internal links were incorrect. - Removed some #overview anchor links, because they don't jump much content. - Made text confirm to suggested proselint and mardownlint rules.
This commit is contained in:
parent
9277223f20
commit
2139df1bfb
|
@ -21,21 +21,21 @@ Before getting started, read through the following docs:
|
||||||
Every document should include the following content in the following sequence:
|
Every document should include the following content in the following sequence:
|
||||||
|
|
||||||
- **Feature name**: defines an intuitive name for the feature that clearly
|
- **Feature name**: defines an intuitive name for the feature that clearly
|
||||||
states what it is and is consistent with any relevant UI text.
|
states what it is and is consistent with any relevant UI text.
|
||||||
- **Feature overview** and description: describe what it is, what it does, and in what context it should be used.
|
- **Feature overview** and description: 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.
|
- **Use cases**: describes real use case scenarios for that feature.
|
||||||
- **Requirements**: describes what software and/or configuration is required to be able to
|
- **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.
|
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.
|
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.
|
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.)
|
(Another doc page, a third party application's site, etc.)
|
||||||
- **Instructions**: clearly describes the steps to use the feature, leaving no gaps.
|
- **Instructions**: clearly describes the steps to use the feature, leaving no gaps.
|
||||||
- **Troubleshooting** guide (recommended but not required): if you know beforehand what issues
|
- **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
|
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
|
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
|
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
|
questions that you know someone might ask. Answering them beforehand only makes your
|
||||||
document better and more approachable.
|
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).
|
For additional details, see the subsections below, as well as the [Documentation template for new docs](#Documentation-template-for-new-docs).
|
||||||
|
|
||||||
|
@ -55,10 +55,11 @@ You should answer this question: what can you do with this feature/change? Use c
|
||||||
are examples of how this feature or change can be used in real life.
|
are examples of how this feature or change can be used in real life.
|
||||||
|
|
||||||
Examples:
|
Examples:
|
||||||
- CE and EE: [Issues](../user/project/issues/index.md#use-cases)
|
|
||||||
- CE and EE: [Merge Requests](../user/project/merge_requests/index.md#overview)
|
- CE and EE: [Issues](../../user/project/issues/index.md#use-cases)
|
||||||
- EE-only: [Geo](https://docs.gitlab.com/ee/gitlab-geo/README.html#overview)
|
- CE and EE: [Merge Requests](../../user/project/merge_requests/index.md)
|
||||||
- EE-only: [Jenkins integration](https://docs.gitlab.com/ee/integration/jenkins.md#overview)
|
- 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
|
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
|
the header `## Overview`, you can omit the header, but keep the content of the
|
||||||
|
@ -72,14 +73,14 @@ and for every **major** feature present in Community Edition.
|
||||||
Your new document will be discoverable by the user only if:
|
Your new document will be discoverable by the user only if:
|
||||||
|
|
||||||
- Crosslinked from the higher-level index (e.g., Issue Boards docs
|
- Crosslinked from the higher-level index (e.g., Issue Boards docs
|
||||||
should be linked from Issues; Prometheus docs should be linked from
|
should be linked from Issues; Prometheus docs should be linked from
|
||||||
Monitoring; CI/CD tutorials should be linked from CI/CD examples).
|
Monitoring; CI/CD tutorials should be linked from CI/CD examples).
|
||||||
- When referencing other GitLab products and features, link to their
|
- When referencing other GitLab products and features, link to their
|
||||||
respective docs; when referencing third-party products or technologies,
|
respective docs; when referencing third-party products or technologies,
|
||||||
link out to their external sites, documentation, and resources.
|
link out to their external sites, documentation, and resources.
|
||||||
- The headings are clear. E.g., "App testing" is a bad heading, "Testing
|
- 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
|
an application with GitLab CI/CD" is much better. Think of something
|
||||||
someone will search for and use these keywords in the headings.
|
someone will search for and use these keywords in the headings.
|
||||||
|
|
||||||
## Documentation template for new docs
|
## Documentation template for new docs
|
||||||
|
|
||||||
|
@ -133,7 +134,7 @@ is simple and the document is short.
|
||||||
- Be clear, concise, and stick to the goal of the doc: explain how to
|
- Be clear, concise, and stick to the goal of the doc: explain how to
|
||||||
use that feature.
|
use that feature.
|
||||||
- Use inclusive language and avoid jargons, as well as uncommon and
|
- Use inclusive language and avoid jargons, as well as uncommon and
|
||||||
fancy words. The docs should be clear and very easy to understand.
|
fancy words. The docs should be clear and easy to understand.
|
||||||
- Write in the 3rd person (use "we", "you", "us", "one", instead of "I" or "me").
|
- Write in the 3rd person (use "we", "you", "us", "one", instead of "I" or "me").
|
||||||
- Always provide internal and external reference links.
|
- Always provide internal and external reference links.
|
||||||
- Always link the doc from its higher-level index.
|
- Always link the doc from its higher-level index.
|
||||||
|
|
Loading…
Reference in New Issue