Sat 11 September 2021
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.