diff options
Diffstat (limited to 'doc/development/documentation/styleguide/index.md')
| -rw-r--r-- | doc/development/documentation/styleguide/index.md | 20 |
1 files changed, 13 insertions, 7 deletions
diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 225db273cb6..7787366dbf4 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -216,15 +216,15 @@ to update. Put files for a specific product area into the related folder: -| Directory | What belongs here | +| Directory | Contents | |:----------------------|:------------------| -| `doc/user/` | User related documentation. Anything that can be done in the GitLab user interface goes here, including usage of the `/admin` interface. | +| `doc/user/` | Documentation for users. Anything that can be done in the GitLab user interface goes here, including usage of the `/admin` interface. | | `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. Administrator settings in the GitLab user interface are under `doc/user/admin_area/`. | -| `doc/api/` | API-related documentation. | +| `doc/api/` | Documentation for the API. | | `doc/development/` | Documentation related to the development of GitLab, whether contributing code or documentation. Related process and style guides should go here. | | `doc/legal/` | Legal documents about contributing to GitLab. | -| `doc/install/` | Contains instructions for installing GitLab. | -| `doc/update/` | Contains instructions for updating GitLab. | +| `doc/install/` | Instructions for installing GitLab. | +| `doc/update/` | Instructions for updating GitLab. | | `doc/topics/` | Indexes per topic (`doc/topics/topic_name/index.md`): all resources for that topic. | ### Work with directories and files @@ -300,11 +300,17 @@ Do not include the same information in multiple places. ## Language -GitLab documentation should be clear and easy to understand. +GitLab documentation should be clear and easy to understand. Avoid unnecessary words. -- Be clear, concise, and stick to the goal of the documentation. +- Be clear, concise, and stick to the goal of the topic. - Write in US English with US grammar. (Tested in [`British.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/British.yml).) - Use [inclusive language](#inclusive-language). +- Rewrite to avoid wordiness: + - there is + - there are + - enables you to + - in order to + - because of the fact that ### Capitalization |