Sourcegraph content guidelines
The goal of these content guidelines is to help us to:
- Create consistency across our product, marketing material, documentation, and handbook.
- Empower our team to make it easier for anyone to write clear, effective, and useful content.
- Drive positive change in language standards to create compassionate, inclusive, and respectful products.
Sections
- Voice and tone helps us speak with a consistent voice.
- Actionable language gives us specific patterns to follow in product and UX copywriting.
- Style & mechanics helps us be clear and consistent in our writing.
- Terminology guidelines give us a source of truth for which words to use.
- Handbook Content Best Practices helps with handbook-specific content structure.
Effectiveness over correctness
These content guidelines aren’t about “correct” and “incorrect” writing. They are about effective writing for our target users. Of course, effectiveness involves correctness to some degree, but only correctness as judged by the audience, not as judged by an appeal to authority.
The examples included in these guidelines are for comparison’s sake, not for exactness.
These guidelines are a living reference, and we welcome changes. The most effective arguments for changes are those based on effectiveness, not correctness.
For further reading, see linguistic prescription on Wikipedia.