[Grok-dev] Re: Rules of Grok document; how to integrate this into the website?

[Brandon Craig Rhodes]

Martijn Faassen <faassen at startifact.com> writes:

> Since there was some comment on the name, I've now renamed it to
> grok_overview.txt, and it's here:...

At least in Atlanta English, an "Overview" is a brief description of
what something is, usually including a high-level list of features.
The sort of thing that a manager, or boss, might read when deciding
whether to use something, or that a developer might read over quickly
before deciding whether to download it.

The best word I know of for this wonderful document is a "Handbook".
There is a long tradition, in the United States at least (British
English might have a different word), of tradesmen having summary
documents of how something works that they keep along with their tools
and that they call a "Handbook".  If you look in, say, the famous
Machinists' Handbook, you won't see any tutorials or sales pitches on
the one hand, nor will you see any long-winded explanations of why a
procedure works and another one doesn't; instead, you just get what
you've written, Martijn - a concise, no-nonsense summary of how
everything works, one piece at a time.

Visit this link and jump to page "50" using the text field to see an
example of the Machinists' Handbook and how it has generally the same
format as this new Grok document:

    http://books.google.com/books?id=4Q8LAAAAIAAJ&pg=PA1&dq=Colvin+%22American+machinists%27+handbook%22#PPR3,M1

-- 
Brandon Craig Rhodes   brandon at rhodesmill.org   http://rhodesmill.org/brandon