Prose Style Guidelines

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 repo, 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.

Goals and audience

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.

Guidelines

We prefer:

Style and usage

Personal pronouns

Structure and markup

Typographical conventions

Terminology, words, and word styling

How to use these guidelines

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.