# Documentation style guide

## I. Core principles

1.  **Clarity:** Write for easy understanding. Prioritize clear, direct, and
    simple language.
2.  **Consistency:** Use consistent terminology, formatting, and style
    throughout the documentation.
3.  **Accuracy:** Ensure all information is technically correct and up-to-date.
4.  **Accessibility:** Design documentation to be usable by everyone. Focus on
    semantic structure, clear link text, and image alternatives.
5.  **Global audience:** Write in standard US English. Avoid slang, idioms, and
    cultural references.
6.  **Prescriptive:** Guide the reader by recommending specific actions and
    paths, especially for complex tasks.

## II. Voice and tone

- **Professional yet friendly:** Maintain a helpful, knowledgeable, and
  conversational tone without being frivolous.
- **Direct:** Get straight to the point. Keep paragraphs short and focused.
- **Second person:** Address the reader as "you."
- **Present tense:** Use the present tense to describe functionality (e.g., "The
  API returns a JSON object.").
- **Avoid:** Jargon, slang, marketing hype, and overly casual language.

## III. Language and grammar

- **Active voice:** Prefer active voice over passive voice.
  - _Example:_ "The system sends a notification." (Not: "A notification is sent
    by the system.")
- **Contractions:** Use common contractions (e.g., "don't," "it's") to maintain
  a natural tone.
- **Simple vocabulary:** Use common words. Define technical terms when
  necessary.
- **Conciseness:** Keep sentences short and focused, but don't omit helpful
  information.
- **"Please":** Avoid using the word "please."

## IV. Procedures and steps

- Start each step with an imperative verb (e.g., "Connect to the database").
- Number steps sequentially.
- Introduce lists of steps with a complete sentence.
- Put conditions before instructions, not after.
- Provide clear context for where the action takes place (e.g., "In the
  administration console...").
- Indicate optional steps clearly (e.g., "Optional: ...").

## V. Formatting and punctuation

- **Text wrap:** Wrap all text at 80 characters, with exceptions for long links
  or tables.
- **Headings, titles, and bold text:** Use sentence case. Structure headings
  hierarchically.
- **Lists:** Use numbered lists for sequential steps and bulleted lists for all
  other lists. Keep list items parallel in structure.
- **Serial comma:** Use the serial comma (e.g., "one, two, and three").
- **Punctuation:** Use standard American punctuation. Place periods inside
  quotation marks.
- **Dates:** Use unambiguous date formatting (e.g., "January 22, 2026").

## VI. UI, code, and links

- **UI elements:** Put UI elements in **bold**. Focus on the task when
  discussing interaction.
- **Code:** Use `code font` for filenames, code snippets, commands, and API
  elements. Use code blocks for multi-line samples.
- **Links:** Use descriptive link text that indicates what the link leads to.
  Avoid "click here."

## VII. Word choice and terminology

- **Consistent naming:** Use product and feature names consistently. Always
  refer to Gemini CLI as `Gemini CLI`, never `the Gemini CLI`.
- **Specific verbs:** Use precise verbs.
- **Avoid:**
  - Latin abbreviations (e.g., use "for example" instead of "e.g.").
  - Placeholder names like "foo" and "bar" in examples; use meaningful names
    instead.
  - Anthropomorphism (e.g., "The server thinks...").
  - "Should": Be clear about requirements ("must") vs. recommendations ("we
    recommend").

## VIII. Files and media

- **Filenames:** Use lowercase letters, separate words with hyphens (-), and use
  standard ASCII characters.
- **Images:** Provide descriptive alt text for all images. Provide
  high-resolution or vector images when practical.

## IX. Accessibility quick check

- Provide descriptive alt text for images.
- Ensure link text makes sense out of context.
- Use semantic HTML elements correctly (headings, lists, tables).