Style guide

Olares documentation is maintained in both English and Simplified Chinese. To ensure a consistent and professional documentation experience, follow the guidelines outlined in this document. These guidelines are inspired by well-known industry style guides such as Microsoft, Google, and IBM.

General principles

1. Clarity: Write in a way that is easy to understand for your target audience.
2. Consistency: Follow the same rules and conventions throughout the documentation.
3. Conciseness: Avoid unnecessary words or redundant phrasing.
4. Accessibility: Use inclusive language and avoid jargon unless it is widely understood by the audience.

Voice and tone

• Voice: Use an active voice wherever possible to make the documentation direct and actionable.
  • Example: Instead of "The file can be downloaded", use "You can download the file".
• Tone: Maintain a professional yet friendly tone across all documentation.
  • Avoid overly casual expressions.
  • Use a neutral, respectful tone.

Terminology

• Use consistent terminology throughout the documentation.
• Avoid ambiguous terms or idiomatic expressions that may not translate well.
• Define technical terms or acronyms on their first use.
  • Example: "Use the Application Programming Interface (API) to communicate between systems."

Capitalization

• Sentence-case capitalization: Capitalize only the first word and proper nouns in headings, titles, and labels.
  • Example: "Create a new file" (not "Create a New File").
• Avoid unnecessary capitalization of words unless they are proper nouns, product names, or brand names.

Point of view

• Use second person point of view to address the user/reader directly.
  • Example: "You can configure the settings in the dashboard."
• Use first person sparingly and only in contexts where it is necessary for clarity or tone.
  • Example: "We recommend using the latest version for better performance."

Punctuation

Dash

• Avoid using em dashes (—) or en dashes (–). Use commas, parentheses, or rephrased sentences instead.

Quotation marks

• Use straight quotation marks (' or ") for English text. Avoid curly quotation marks.
• Place punctuation outside closing quotation marks in English unless it is part of the quoted material.
• For nested quotes, use single quotation marks inside double quotation marks.

Semicolon

• Do not use semicolons in either English or Chinese. Use a period or conjunction to separate clauses instead.

Formatting and Style

• Lists:
  • Use bulleted lists for unordered items.
  • Use numbered lists for sequential steps or prioritized items.
• Code:
  • Use inline code formatting for code snippets, commands, or file names.
    • Example: git commit -m "Message"
  • Use code blocks for longer examples.
• UI elements:
  • Use bold to refer to UI elements like buttons, menu options, and field names.
    • Example: Click Submit to complete the process.

Referring to UI controls

• Avoid directly referring to UI controls like "button", "menu", or similar terms unless absolutely necessary. This ensures a smoother and more natural reading experience.
  • Example: Instead of "Click the Save button to apply changes", use "Click Save to apply changes".

Inclusive language

• Avoid gendered pronouns. Use plural or neutral constructions instead.
  • Example: Use "they/them" instead of "he/she".
• Use inclusive terms:
  • Instead of "master/slave", use "primary/secondary" or "leader/follower".
  • Instead of "whitelist/blacklist", use "allowlist/blocklist".

Chinese-specific guidelines

Point of View

• Use "你" instead of "您" to address users. The term "您" can feel too formal and create a sense of distance.

Mixed Chinese and English text

• When mixing Chinese and English text, ensure there is a space before and after the English text for better readability.
  • Example: "请点击 Save 继续。"

Simplified Chinese standards

• Follow Simplified Chinese conventions for punctuation, spacing, and grammar.
• Use Chinese full-width punctuation*for Chinese text:
  • Example: Use 。 instead of . for periods in Chinese.

Avoid ambiguity

• Avoid translating technical terms into Chinese if the English term is widely accepted (e.g., API, HTTP).
  • Example: Use "API" instead of "应用程序接口".