From the GitHub Manual of Style, which this style guide inherits from:
Words are an important part of how software works. Just as we have a style guide for our code, we have a style guide for our tone and our voice. Even though there may be dozens of people creating a product, it should still sound like we speak in one consistent voice.
In other words, the way we write is just as important as the way we design. Consider these things when writing copy.
All written content should follow these principles:
- Approachability: Don't assume reader has prior knowledge
- Brevity: Keep it simple, link to outside content for deeper dives
- Curation: Amplify community best practices vs. any individual's point of view
Content should maintain a light-hearted, but wise (think classy, not overly excited) tone. Open source is fun! Readers should feel inspired, not discouraged, by the tone of your writing, and they should trust you to help them get started.
When referring to people that use GitHub, use @mentions of their username instead of their full name.
- 😄 As @AliceBillington put it...
- 😢 As Alice Billington put it...
When referring to a project on GitHub, link to the repository so others can dive deeper, if they choose.
- 😄 @CharlesDon took a similar approach to Hodl...
- 😢 @CharlesDon took a similar approach to Hodl...