Purpose
This guide defines the tone, voice, and structural conventions for all technical documentation in the Cappuccino project. Its goal is to ensure clarity, neutrality, and international accessibility, making no assumptions about the reader’s technical domain, linguistic background, or cultural context.
This style guide applies equally to standalone documentation (e.g., README files, user guides) and to documentation embedded within code (e.g., comments, docstrings, inline usage instructions).
- We write to inform, not to entertain.
- We respect our reader’s time and attention.
- We strive for writing that is precise, impersonal, and free from assumption.
1. Tone and Voice
Use a neutral, formal tone.
Avoid injecting personality, enthusiasm, or casual warmth. Documentation is not marketing material nor a conversation — it is a tool.
Avoid: “Let’s go ahead and get the server running.”
Prefer: “Start the server.”
Use passive voice where appropriate.
Passive voice removes assumptions about the reader and centers attention on the system or action.
Avoid: “You configure the database before running the app.”
Prefer: “The database must be configured before the application is run.”
Rationale: Passive voice preserves neutrality and avoids assigning the reader a role or responsibility that may not apply.
Avoid using direct address ("you")
Avoid: “You should see the login screen.”
Prefer: “The login screen appears.”
2. Diction and Word Choice
Avoid usage of slang, idioms, and spoken contractions
Words like "gonna," "wanna," "gotcha," "cool," or phrases like "go ahead and" or "kinda" are strictly disallowed.
Avoid: “You’re gonna wanna restart the service.”
Prefer: “Restart the service.”
Avoid filler and emotional language
Words such as “just,” “simply,” and “easy” imply judgment about the task or the reader’s competence.
Avoid: “Just clone the repo and you’re done!”
Prefer: “Clone the repository to proceed.”
3. Structure and Clarity
Write declaratively
Each sentence should assert one clear fact, step, or outcome.
“The installer copies files to
/opt/cappuccino.”
Use imperative mood for commands
“Run the setup script.”
Avoid embellish with optional verbs ("try to", "maybe"). State what must happen.
Explain context before action
Always tell the reader why something is being done or what result is expected. Never leave outcomes implicit.
“To prepare the runtime environment, install the dependencies listed in
package.json.”
4. Cultural and Linguistic Accessibility
Write for an international audience
Avoid culturally specific references, jokes, or idioms. Use standard English that is globally intelligible.
Prefer consistent terminology
Use technical terms consistently. Avoid switching between synonyms (e.g., using “application”, “app” and “program” interchangeably. Use the same term throughout).
5. Tools and Enforcement
We encourage contributors to:
- Use LLM-based assistants (e.g., GPT) in editor integrations to revise drafts for neutrality and tone.
- Submit documentation through a CI-based linter or reviewer if available.
- Use this guide as the standard for pull request reviews involving written content.
6. Philosophy
“Good documentation does not assume who the reader is. It assumes they are looking for clarity, rather than social interaction.”
Professional tone is respectful tone. Our goal is reduction of cognitive friction. We document in the spirit of precision, rather than personality.