Skip to content

tone-of-voice.md

Latest commit

 

History

History
120 lines (81 loc) · 4.47 KB

tone-of-voice.md

File metadata and controls

120 lines (81 loc) · 4.47 KB

✍️ 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.