@@ -15,7 +15,7 @@ For programmatic help adhering to the guidelines, see [linting](index.md#linting
## Files
-[Directory structure](index.md#location-and-naming-documents): place the docs
in the correct location.
in the correct location.
-[Documentation files](index.md#documentation-files): name the files accordingly.
DANGER: **Attention:**
...
...
@@ -29,7 +29,7 @@ a test that will fail if it spots a new `README.md` file.
### Markdown
The [documentation website](https://docs.gitlab.com) had its markdown engine migrated from [Redcarpet to GitLab Kramdown](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/108)
in October, 2018.
in October 2018.
The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown)
gem will support all [GFM markup](../../user/markdown.md) in the future. For now,
...
...
@@ -45,38 +45,38 @@ yield a useful result, and ensuring content is helpful and easy to consume.
- What to include:
- Any and all helpful information, processes, and tips for implementing,
using, and troubleshooting GitLab features. [The documentation is the single source of truth](https://about.gitlab.com/handbook/documentation/#documentation-as-single-source-of-truth-ssot)
for this information.
using, and troubleshooting GitLab features. [The documentation is the single source of truth](https://about.gitlab.com/handbook/documentation/#documentation-as-single-source-of-truth-ssot)
for this information.
- 'Risky' or niche problem-solving steps. There is no reason to withhold these or
store them elsewhere; simply include them along with the rest of the docs including all necessary
detail, such as specific warnings and caveats about potential ramifications.
store them elsewhere; simply include them along with the rest of the docs including all necessary
detail, such as specific warnings and caveats about potential ramifications.
- Any content types/sources, if relevant to users or admins. You can freely
include presentations, videos, etc.; no matter who it was originally written for,
if it is helpful to any of our audiences, we can include it. If an outside source
that's under copyright, rephrase, or summarize and link out; do not copy and paste.
include presentations, videos, etc.; no matter who it was originally written for,
if it is helpful to any of our audiences, we can include it. If an outside source
that's under copyright, rephrase, or summarize and link out; do not copy and paste.
- All applicable subsections as described on the [structure and template](structure.md) page,
with files organized in the [correct directory](index.md#documentation-directory-structure).
with files organized in the [correct directory](index.md#documentation-directory-structure).
- To ensure discoverability, link to each doc from its higher-level index page and other related pages.
- 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.
- Do not duplicate information.
- Structure content in alphabetical order in tables, lists, etc., unless there is
a logical reason not to (for example, when mirroring the UI or an ordered sequence).
a logical reason not to (for example, when mirroring the UI or an ordered sequence).
## Language
- Use inclusive language and avoid jargon, as well as uncommon
words. The docs should be clear and easy to understand.
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").
- Be clear, concise, and stick to the goal of the doc.
- Write in US English.
- Capitalize "G" and "L" in GitLab.
- Use title case when referring to [features](https://about.gitlab.com/features/) or
Issue Boards, GitLab Core, Git, Prometheus, Kubernetes, etc), and methods or methodologies
(e.g., Continuous Integration, Continuous Deployment, Scrum, Agile, etc). Note that
some features are also objects (e.g. "GitLab's Merge Requests support X." and "Create a new merge request for Z.").
## Text
...
...
@@ -127,9 +127,9 @@ Check specific punctuation rules for [list items](#list-items) below.
**Markup:**
- Use dashes (`- `) for unordered lists instead of asterisks (`* `).
- Use dashes (`-`) for unordered lists instead of asterisks (`*`).
- Use the number one (`1`) for each item in an ordered list.
When rendered, the list items will appear with sequential numbering.
When rendered, the list items will appear with sequential numbering.
**Punctuation:**
...
...
@@ -226,12 +226,11 @@ For other punctuation rules, please refer to the
To indicate the steps of navigation through the UI:
- Use the exact word as shown in the UI, including any capital letters as-is.
- Use bold text for navigation items and the char "greater than" (`>`) as separator
(e.g., `Navigate to your project's **Settings > CI/CD**` ).
(e.g., `Navigate to your project's **Settings > CI/CD**` ).
- If there are any expandable menus, make sure to mention that the user
needs to expand the tab to find the settings you're referring to (e.g., `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`).
needs to expand the tab to find the settings you're referring to (e.g., `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`).
## Images
...
...
@@ -246,7 +245,7 @@ needs to expand the tab to find the settings you're referring to (e.g., `Navigat
- Compress all images with <https://tinypng.com/> or similar tool.
- Compress gifs with <https://ezgif.com/optimize> or similar tool.
- Images should be used (only when necessary) to _illustrate_ the description
of a process, not to _replace_ it.
of a process, not to _replace_ it.
- Max image size: 100KB (gifs included).
- The GitLab docs do not support videos yet.
...
...
@@ -266,12 +265,12 @@ Inside the document:
## Code blocks
- Always wrap code added to a sentence in inline code blocks (``` ` ```).
