Technical Documentation, like Code, does not follow English rules for grammar and style

The purpose of technical documentation is to precisely convey information to other people who possess the technical skills needed to apply it.  It is not to pass along technical skills, although reading technical documentation on a system designed by someone more experienced often will.  It is not to explain a system to management to enable their decision-making processes, that need is properly met by the inclusion of executive summaries and project plans in software specifications alongside the technical design.  And it is decidedly not to make the spelling and grammar check in your word processor happy.

Of course, documentation must include explanations in a human language such as English, and as such, broken rules of English grammar and style are distracting and doing so gratuitously should be avoided.  But the potential for conflict with accuracy should not be ignored.  In order to be clear when documenting code, it is necessary to follow the rules established by the programming language for identifying particular components.  Only where the programming language makes no restriction (such as in comments, or the English prose surrounding references to the software system) should literary rules reign.

Joseph Newcomer has a great anecdote of a programmer who tried to write C++ code using English grammar.  But documentation can become complicit in such foolishness if it disregards the rules of the language, as does the Apple Developer Documentation.  Here is an excerpt taken from Apple's man page for select on 1 August 2009:

First, the prototype, which has been correctly preserved:

int select(int nfds, fd_set *restrict readfds, fd_set *restrict writefds, fd_set *restrict errorfds, struct timeval *restrict timeout);

Next, the explanatory content, in which accuracy has been sacrificed on the altar of English grammar:

DESCRIPTION Select() examines the I/O descriptor sets...

RETURN VALUES Select() returns the number of ready descriptors...

BUGS Select() should probably have been designed to...

I'm truly at a loss for why Apple should be describing the Select() function in a document dedicated to select().  No C compiler accepts the altered capitalization, and neither should programmers.  Oh wait, Apple was just following the example of FreeBSD who messed up a decade earlier.  Of course, FreeBSD is free, while Apple is selling their OS and therefore should be held to a higher standard.  For reference, the normative specification of select (and updated version) are case-correct while also managing to obey English capitalization rules.  This is the ideal.

Maybe next, in the interests of using a larger vocabulary to avoid boring repetition, the cat man page can be rewritten using words such as "feline".  head and tail likewise have perfectly good synonyms (in English only, /bin/sh isn't accepting substitutes).  Just don't ask me to build products on a foundation that plays such tricks with documentation.