1

General style reference

Calvin W. edited this page 2025-07-17 15:00:37 +08:00

Table of Contents

• General principles
• Voice and tone
• Terminology
• Capitalization
• Point of view
• Punctuation
• Dash
• Quotation marks
• Semicolon
• Formatting and Style
• Referring to UI controls
• Inclusive language
• Chinese-specific guidelines
• Point of View
• Mixed Chinese and English text
• Simplified Chinese standards
• Avoid ambiguity

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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 "应用程序接口".