Bazel docs style guide “Defining Principles”

These are the “Defining Principles” for the Bazel documentation, from the Bazel docs style guide:

  • Concise. Use as few words as possible.
  • Clear. Use plain language. Write without jargon for a fifth-grade reading level.
  • Consistent. Use the same words or phrases for repeated concepts throughout the docs.
  • Correct. Write in a way where the content stays correct for as long as possible by avoiding time-based information and promises for the future.

As technical writing goes, those are some smart ideas. Some time after I created this website I learned, “Anything I write here I have to maintain,” and it turns out that’s a lot of work.