diff options
author | Matt Penna <mpenna@gitlab.com> | 2019-09-06 19:22:02 +0000 |
---|---|---|
committer | Matt Penna <mpenna@gitlab.com> | 2019-09-06 19:22:02 +0000 |
commit | 50956dd6442777c56f797ca32fedda0ade430280 (patch) | |
tree | 9b5d441d98b5d1c71ee9418a622cfcdc33c7fc0d | |
parent | 1ffa66effbc9272ac9755ba29fab2fd1b3d93db5 (diff) | |
download | gitlab-ce-50956dd6442777c56f797ca32fedda0ade430280.tar.gz |
Proposed several style guide additions
-rw-r--r-- | doc/development/documentation/styleguide.md | 12 |
1 files changed, 12 insertions, 0 deletions
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 09dd31e2aee..6222db1a8cb 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -221,6 +221,18 @@ Do not include the same information in multiple places. [Link to a SSOT instead. 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."). +- Avoid use of the future tense. + - Instead of, "After you execute this command, the result will be displayed", say "After you execute this command, the result is displayed." + - Only use the future tense to convey when the action or result will actually occur at a future time. +- Do not use contractions. + - Say "do not", "cannot", or "does not" instead of "don't", "can't", "doesn't", and so on. + - Possible exceptions are cases when a more familiar tone is desired, such as a blog post or other conversational context. +- Do not use slashes to clump different words together. + - Instead of "and/or", consider saying "or", or use another sensible construction. + - Other examples include "author/asignee" and "namespace/repository name". Break apart any such instances in an appropriate way. +- Do not use "may" and "might" interchangeably. + - Use "might" to indicate the probability of something occurring. "If you skip this step, the import process might fail." + - Use "may" to indicate giving permission for someone to do something, or consider using "can", instead. "You may select either option on this screen." Or, "you can select either option on this screen." ## Text |