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 easier for anyone to write clear, effective, and useful content.
  • Drive positive change in language standards to create compassionate, inclusive, and respectful products.

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.

Sections

Voice and tone

Actionable language

Style & mechanics

Terminology guidelines

Other good references