4.5 KiB
✍️ Documentation Tone of Voice
This tone of voice guide helps you to write documentation that reflects the values and personality of the FAIR Package Manager Project. Clear, inclusive, and supportive documentation ensures everyone, from newcomers to experts, can confidently understand, use, and contribute to the project.
🧭 Our Voice in a Nutshell
Voice traits:
| Trait | Description |
|---|---|
| Friendly | Write like you're helping a friend or colleague, not issuing commands. |
| Clear | Use plain language. Avoid jargon unless absolutely necessary. Remember we are a global community and not everything translates! |
| Supportive | Assume good intentions. Encourage contributors and users alike. |
| Precise | Accuracy is critical, especially in technical steps and code examples. |
| Inclusive | Avoid assumptions. Speak to a global, diverse, and cross-disciplinary audience. |
💬 Writing Style Principles
1. Use Plain Language
- ✅ “Click the Submit button to continue.”
- ❌ “Engage the user input interface and execute the form submission procedure.”
2. Be Direct, But Courteous
- ✅ “To start the server, run the following command.”
- ❌ “You may want to consider running the following, if you feel that’s appropriate.”
3. Use Active Voice
- ✅ “Install the package using the CLI.”
- ❌ “The package should be installed by the user using the CLI.”
4. Avoid Assumptions
The reader may be:
- New to open source
- Unfamiliar with your environment
- Using a screen reader
- On a slow or unstable internet connection
✨ Inclusive and Welcoming Language
Our documentation should feel accessible to people of all backgrounds, levels, and abilities. Small choices in language can have a big impact on inclusion.
- Use gender-neutral pronouns (they/them) unless a person's pronouns are specified.
- Avoid idioms and metaphors—they often don’t translate well.
- ❌ “Hit the ground running”
- ✅ “Start contributing quickly”
- Avoid gatekeeping or assumed knowledge.
- ❌ “Obviously…”
- ❌ “Simple task…”
- ✅ “If you're new to this, here's where to start.”
- Prefer inclusive technical terms where possible:
- ✅ “Allowlist/Blocklist” instead of “Whitelist/Blacklist”
- ✅ “Primary/Replica” instead of “Master/Slave”
These guidelines align with best practices for psychological safety, cultural sensitivity, and technical precision as defined by the Inclusive Naming Initiative.
🛠️ Technical Language
Use code and CLI examples:
git clone https://github.com/FAIR/your-repo-name
# Clones the repository locally
Introduce new terms clearly:
- Define them the first time they’re used
- Link to helpful external references when appropriate
📚 Structural Tips
-
Headings: Use a clear hierarchy (
##,###, etc.) -
Lists: Use bullet or numbered lists for steps or options
-
Callouts:
Note: For helpful context Warning: For potential issues Tip: For optional but useful enhancements
🤝 Encouraging Contributions in Docs
- Reinforce that docs are code and just as valuable
- Invite everyone to contribute:
- ✅ “Spotted a typo? You can fix it in a few clicks.”
- ✅ “You don’t need to be a developer to contribute to documentation.”
✅ Tone in Action: Before and After
| Before | After |
|---|---|
| “You must run this or it won’t work.” | “Run this command to start the process.” |
| “Only advanced users should try this.” | “This step requires some familiarity with Docker.” |
| “Just clone the repo and go.” | “Start by cloning the repository using the command below.” |
🧾 Final Reminders
- Write for humans. Then double-check for accuracy.
- Keep docs up-to-date. Reflect the latest changes.
- Ask for feedback. Collaboration improves quality.
- Celebrate contributions. Every fix or improvement matters.
