@@ -19,7 +19,7 @@ that apply to all GitLab content, not just documentation.
The documentation of GitLab products and features is the SSOT for all information related to implementation, usage, and troubleshooting. It evolves continually, in keeping with new products and features, and with improvements for clarity, accuracy, and completeness.
This policy prevents information silos, ensuring that it remains easy to find information about GitLab products.
This policy prevents information silos, making it easier to find information about GitLab products.
It also informs decisions about the kinds of content we include in our documentation.
...
...
@@ -61,7 +61,7 @@ Instead, link to the SSOT and explain why it is important to consume the informa
### Organize by topic, not by type
Beyond top-level audience-type folders (for example, `administration`), we organize content by topic, not by type, so that it can be located as easily as possible within the single-source-of-truth (SSOT) section for the subject matter.
Beyond top-level audience-type folders (for example, `administration`), we organize content by topic, not by type, so it can be located as easily as possible within the single-source-of-truth (SSOT) section for the subject matter.
For example, do not create groupings of similar media types. For example:
...
...
@@ -76,7 +76,7 @@ and cross-link between any related content.
### Docs-first methodology
We employ a **docs-first methodology** to help ensure that the docs remain a complete and trusted resource, and to make communicating about the use of GitLab more efficient.
We employ a **docs-first methodology** to help ensure the docs remain a complete and trusted resource, and to make communicating about the use of GitLab more efficient.
- If the answer to a question exists in documentation, share the link to the docs instead of rephrasing the information.
- When you encounter new information not available in GitLab’s documentation (for example, when working on a support case or testing a feature), your first step should be to create a merge request (MR) to add this information to the docs. You can then share the MR in order to communicate this information.
...
...
@@ -129,13 +129,13 @@ correctly, but is not the current standard for GitLab documentation).
A rule that could cause confusion is `MD044/proper-names`, as it might not be immediately
clear what caused markdownlint to fail, or how to correct the failure. This rule
checks a list of known words, listed in the `.markdownlint.json` file in each project,
to verify that proper capitalization and backticks are used. Words in backticks will
to verify proper use of capitalization and backticks. Words in backticks will
be ignored by markdownlint.
In general, product names should follow the exact capitalization of the official names
of the products, protocols, and so on.
Some examples that will fail if incorrect capitalization is used:
Some examples fail if incorrect capitalization is used:
- MinIO (needs capital `IO`)
- NGINX (needs all capitals)
...
...
@@ -252,6 +252,8 @@ GitLab documentation should be clear and easy to understand.
- Avoid uncommon words.
- Don't write in the first person singular.
- Instead of "I" or "me," use "we," "you," "us," or "one."
- When possible, stay user focused by writing in the second person ("you" or the imperative).
- Don't overuse "that". In many cases, you can remove "that" from a sentence and improve readability.
