This is a set of style and usage guidelines for Homebrew’s prose documentation aimed at users, contributors, and maintainers (as opposed to executable computer code). It applies to documents like those in docs
in the Homebrew/brew
repository, announcement emails, and other communications with the Homebrew community.
This does not apply to any Ruby or other computer code. You can use it to inform technical documentation extracted from computer code, like embedded man pages, but it’s just a suggestion there.
The primary goal of Homebrew’s prose documents is communicating with its community of users and contributors. “Users” includes “contributors” here; wherever you see “users” you can substitute “users and contributors”.
Understandability trumps any particular style guideline.
Users trump maintainers, except in specifically maintainer-focused documents.
Homebrew’s audience includes users with a wide range of education and experience, and users for whom English is not a native language. We aim to support as many of those users as feasible.
We strive for “correct” but not “fancy” usage. Think newspaper article, not academic paper.
This is a set of guidelines to be applied using human judgment, not a set of hard and fast rules. It is like The Economist’s Style Guide or Garner’s Modern American Usage. It is less like the Ruby Style Guide. All guidelines here are open to interpretation and discussion. 100% conformance to these guidelines is not a goal.
The intent of this document is to help authors make decisions about clarity, style, and consistency. It is not to help settle arguments about who knows English better. Don’t use this document to be a jerk.
We prefer:
fixed width font
<...>
brackets git remote add <my-user-name> https://github.com/<my-user-name>/homebrew-core.git
git
and brew
are styled in fixed width font
BLAH
to 5”, not “Set $BLAH
to 5”homebrew/core
are styled in fixed width font
. Repository names may be styled in either fixed width font like “Homebrew/homebrew-core
”, as links like “Homebrew/homebrew-core”, or regular text like “Homebrew/homebrew-core”, based on which looks best for a given use. Refer to these guidelines to make decisions about style and usage in your own writing for Homebrew documents and communication.
PRs that fix style and usage throughout a document or multiple documents are okay and encouraged. PRs for just one or two style changes are a bit much.
Giving style and usage feedback on a PR or commit that involves documents is okay and encouraged. But keep in mind that these are just guidelines, and for any change, the author may have made a deliberate choice to break these rules in the interest of understandability or aesthetics.
© 2009–present Homebrew contributors
Licensed under the BSD 2-Clause License.
https://docs.brew.sh/Prose-Style-Guidelines.html