Posted on Sat 11 September 2021

an element of style

I just realized that I internalized the O’Reilly house style decades ago, and so I think it’s the proper way to write documentation.

Primary elements: the document, even at book length, takes the form of a precise, pedantic, but informal letter to the audience. The author might reference themself as “I” and tell brief anecdotes to contextualize the material, and frequently encourages the reader in the second person:

You can also reticulate the frobnitz with the ‘–frob-harder’ switch if that feels more natural to you.

As a side effect, this style of technical writing minimizes the number of gendered pronouns, which I always prefer because I don’t know who is reading the work.


© -dsr-. Send feedback or comments via email — by continuing to use this site you agree to certain terms and conditions.

Built using Pelican. Derived from the svbhack theme by Giulio Fidente on github.