mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-02-01 22:48:03 +00:00
97 lines
3.9 KiB
Markdown
97 lines
3.9 KiB
Markdown
# 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).
|