Thank you for contributing to Bazel’s documentation. This serves as a quick
documentation style guide to get you started. For any style questions not
answered by this guide, follow the
Google developer documentation style guide.
Each page should have one purpose and that should be defined at the
beginning. This helps readers find what they need quicker.
Yes: This page covers how to install Bazel on Windows.
No: (No introductory sentence.)
At the end of the page, tell the reader what to do next. For pages where
there is no clear action, you can include links to similar concepts,
examples, or other avenues for exploration.
In Bazel documentation, the audience should primarily be users—the people using
Bazel to build their software.
Address your reader as “you”. (If for some reason you can’t use “you”,
use gender-neutral language, such as they.)
Yes: To build Java code using Bazel,
you must install a JDK.
MAYBE: For users to build Java code with Bazel, they must install a JDK.
No: For a user to build Java code with
Bazel, he or she must install a JDK.
If your audience is NOT general Bazel users, define the audience at the
beginning of the page or in the section. Other audiences can include
maintainers, contributors, migrators, or other roles.
Avoid “we”. In user docs, there is no author; just tell people what’s
possible.
Yes: As Bazel evolves, you should update your code base to maintain
compatibility.
No: Bazel is evolving, and we will make changes to Bazel that at
times will be incompatible and require some changes from Bazel users.
Where possible, avoid terms that orient things in time, such as referencing
specific dates (Q2 2022) or saying “now”, “currently”, or “soon.” These go
stale quickly and could be incorrect if it’s a future projection. Instead,
specify a version level instead, such as “Bazel X.x and higher supports
<feature> or a GitHub issue link.
Yes: Bazel 0.10.0 or later supports
remote caching.
No: Bazel will soon support remote
caching, likely in October 2017.
Use present tense. Avoid past or future tense unless absolutely necessary
for clarity.
Yes: Bazel issues an error when it
finds dependencies that don’t conform to this rule.
No: If Bazel finds a dependency that
does not conform to this rule, Bazel will issue an error.
Where possible, use active voice (where a subject acts upon an object) not
passive voice (where an object is acted upon by a subject). Generally,
active voice makes sentences clearer because it shows who is responsible. If
using active voice detracts from clarity, use passive voice.
Yes: Bazel initiates X and uses the
output to build Y.
No: X is initiated by Bazel and then
afterward Y will be built with the output.
For readability, wrap lines at 80 characters. Long links or code snippets
may be longer, but should start on a new line. For example:Note: Where possible, use Markdown instead of HTML in your files. Follow the
GitHub Markdown Syntax Guide
for recommended Markdown style.
Code samples are developers’ best friends. You probably know how to write these
already, but here are a few tips.If you’re referencing a small snippet of code, you can embed it in a sentence.
If you want the reader to use the code, such as copying a command, use a code
block.
