Skip to content

Latest commit

 

History

History
108 lines (73 loc) · 5.06 KB

docs-style-guide.md

File metadata and controls

108 lines (73 loc) · 5.06 KB
Raw

About this guide 👋

Welcome to our simple and straightforward style guide! We created this guide for our community of tech and non-tech experts to ensure we communicate effectively and inclusively. This guide is divided into four sections:

Inclusive Language 🌎

Inclusive language is an essential aspect of communication. It promotes equality, respects diversity, and avoids offense. Here are some best practices to follow:

  • Use gender-neutral words for common terms

    • ❌ Not this: A maintainer should try to be kind yet constructive in his feedback.
    • ✅ Use this: A maintainer should try to be kind yet constructive in their feedback.

  • Avoid using terms that have colonialistic or racist connotations.

    • ❌ Not this: Contributors should push their pull requests to the master branch.
    • ✅ Use this: Contributors should push their pull requests to the main branch.

Grammar & Mechanics 📝

Grammar and mechanics help ensure that your writing is clear, concise, and easy to understand. Here are some best practices to follow:

Commas

  • Use commas when describing lists.

    • ❌ Not this: You can also add your timeline testimonials and upcoming events that you are participating in.
    • ✅ Use this: You can also add your timeline, testimonials, and upcoming events that you are participating in.

  • Use commas in introductory elements.

    • ❌ Not this: If you do not have one yet you can create one for free with an email address and password.
    • ✅ Use this: If you do not have one yet, you can create one for free with an email address and password.

  • Use commas before the seven, so-called, coordinating conjunctions (and, but, so, for, nor, yet, or) to separate two independent clauses.

    • ❌ Not this: There are 4 ways you can add your profile but for this Quickstart, we will use the GitHub UI.
    • ✅ Use this: There are 4 ways you can add your profile, but for this Quickstart, we will use the GitHub UI.

Capitalisation

  • Only capitalize terms that describe a product, its feature, the first letter of a sentence, or a person’s name.
    • ❌ Not this: There are 4 ways you can add your profile, but for this quickstart we will use the github ui.
    • ✅ Use this: There are 4 ways you can add your profile, but for this Quickstart, we will use the GitHub UI.

Clarity 🤔

Clarity in writing helps ensure that your audience understands your message and intentions. Here are some best practices to follow:

Active vs. Passive

Using the active voice in writing makes your message more direct and engaging.

  • ❌ Not this: This repo is maintained by a team of people.
  • ✅ Use this: A team of people maintains this repo.

Jargon

Using technical and coding jargon can alienate non-technical readers.

  • ❌ Not this: Before submitting your code review, it is always helpful to add comments such as LGTM! in the textbox.
  • ✅ Use this: Before submitting your code review, it is always helpful to add comments such as Great job! in the textbox.

Accessibility ♿

Bullet Points

  • Avoid describing things only by their color or position.
    • ❌ Not this: see the image above.
    • ✅ Use this: See Image 2.2.

Emojis

  • Avoid using emojis as bullet points or numbered lists.

  • ❌ Not this: 1️⃣ Fork the repository

  • 2️⃣ Visit the Accessibleforall repository

    • ✅ Use this: 1. Fork the repository

  • 2️. Visit the Accessibleforall repository

  • Avoid using emojis in the middle of a sentence.

    • ❌ Not this: There are 4️⃣ ways you can add your profile, but for this Quickstart we will use the GitHub UI.

  • ✅ Use this: There are 4 ways you can fix your profile, but for this tutorial, we will use the GitHub UI.

  • Use them sparingly at the end of a sentence.

    • ❌ Not this: Join the conversation on our Discord community! 😀 😄 🎉
    • ✅ Use this: Join the conversation on our Discord community! 😀

Headings

  • Use descriptive titles for headings.

    • ❌ Not this: <h1> Yoga</h1>

  • ✅ Use this: <h1>Yoga for Developers</h1>

  • Place headings in sequential order.

  • ❌ Not this: <h1>Yoga for Developers</h1> <h3>What is Yoga?</h3> <h2>The History of Yoga</h2>

    • ✅ Use this: <h1>Yoga for Developers</h1> <h2>What is Yoga?</h2> <h3>The History of Yoga</h3>

Images

  • Use descriptive alt text for images.
  • ❌ Not this: ![Cat_2019-06-14.jpg](https://en.wikipedia.org/wiki/File:June_odd-eyed-cat.jpg)
  • ✅ Use this: ![A white cat with a blue eye and golden eye is sitting on a grey couch](https://en.wikipedia.org/wiki/File:June_odd-eyed-cat.jpg)

Have some ideas for improving the guide? Raise an issue on our GitHub page. We would love to receive your feedback!