---
tags:
  - style guide 
---
# useful words

from the style guide[^1]

- Use active voice instead of passive voice
- Use present tense instead of past or future tense, unless necessary
- Use concrete and specific language instead of abstract or vague language
- Use short sentences and paragraphs to improve readability
- Use bullet points and lists to break up long blocks of text
- Use headings and subheadings to organize content
- Use descriptive and meaningful titles for headings and articles
- Use simple and consistent formatting for code examples and snippets
- Use meaningful variable and function names in code
- Use consistent naming conventions for files, folders, and URLs
- Use inclusive language that is respectful and avoids assumptions or stereotypes
- Use clear and concise language that is easy to understand
- Use correct grammar, spelling, and punctuation
- Use GitLab terminology consistently and accurately
- Use caution when using humor or slang, as it may not be understood or appreciated by all readers
- Use examples and visual aids to clarify concepts when possible

### avoid

- simply
- obviously
- basically
- clearly
- just
- easy
- obviously
- of course
- everyone knows that
- however
- unfortunately

> if you must

- Instead of "simply": use "just" or "merely" when appropriate, or rephrase the sentence to make it more specific
- Instead of "obviously": use "clearly" or "evidently", or consider explaining the concept more thoroughly
- Instead of "basically": use "essentially" or "fundamentally"
- Instead of "clearly": use "evidently" or "apparently", or consider providing more context to clarify the meaning
- Instead of "just": use "only" or "solely" when appropriate, or rephrase the sentence to make it more specific
- Instead of "easy": use "simple" or "straightforward", or consider providing more context or explanation to make the concept easier to understand
- Instead of "of course": consider rephrasing the sentence to make the meaning more clear, or using a different phrase such as "naturally" or "undoubtedly"
- Instead of "everyone knows that": consider rephrasing the sentence to provide more context or explanation, or using a different phrase such as "as you may already know" or "as is widely known"
- Instead of "however": use "but" or "yet" when appropriate, or rephrase the sentence to make the meaning more clear
- Instead of "unfortunately": consider using a different phrase such as "regrettably" or "sadly"

[^1]:<https://docs.gitlab.com/ee/development/documentation/styleguide/>
