Writing Style Guide
Style and Tone
APEX documentation should be clear, concise, and user-friendly. Write in a way that is accessible to both new and experienced users.
Use Active Voice
Use active voice whenever possible.
Yes: Update the settings before continuing.
No: The settings should be updated before continuing.
Use Present Tense
Use the present tense unless referring to past events.
Yes: The API returns data in JSON format.
No: The API will return data in JSON format.
Use Second Person
Address the reader as "you" instead of "the user."
Yes: You can configure the settings in the dashboard.
No: The user can configure the settings in the dashboard.
Grammar and Mechanics
Capitalization
- Capitalize "APEX" at all times.
- Use sentence case for headings (e.g., "Managing API Keys" instead of "Managing API keys").
Numbers
- Use numerals for numbers 10 and above.
- Spell out numbers one through nine unless used in technical contexts.
Acronyms and Abbreviations
- Spell out acronyms on first use, followed by the abbreviation in parentheses.
- Example: "Representational State Transfer (REST)"
Formatting
Headings
Use headings to organize content clearly.
- Use
##for second-level headings. - Use
###for third-level headings.
Lists
Use bulleted lists for unordered content and numbered lists for sequential steps.
Example:
- APEX CLI
- APEX API
- Install the APEX CLI.
- Authenticate using your API key.
Code Blocks
Use inline code for short snippets and fenced code blocks for multi-line code examples.
Example:
Inline code: npm install apex-cli
Fenced code block:
{
"key": "value"
}
Links
Use descriptive link text.
Yes: Read more about authentication.
No: Click here.
Terminology
- "Sign in" (not "Log in" or "Login" as a verb).
- "Set up" (verb) vs. "Setup" (noun).
- "E.g." (use a comma after) and "i.e." (use a comma after).
Examples
Incorrect:
The settings should be updated before continuing.
Correct:
Update the settings before continuing.
By following this guide, we ensure that APEX documentation is clear, consistent, and user-friendly.