syntax summary as documentation key (was re style)

[Michael Turner]

On 2/15/2010, "Jayson Vantuyl" <kagato@REDACTED> wrote:

>... The average person that dives into the docs doesn't always
>find these little corners.  There are qualities of good documentation
>beyond mere existence.

Indeed.  Not to harp on a recent point, but this is why I like having an
appendix for a syntax summary.  It's not the Lives of the Saints in all
their gory detail, but it does give you line-of-sight to all the
stations of the cross.  (To use a metaphor that probably falls flat if
you've seldom been inside a Catholic church.)

In the ranking of "table of contents", "index", and "syntax
summary", I'd say "syntax summary" runs a close third behind
"index"-- though it's almost useless without an index in which every
almost every grammar symbol, terminal and non-terminal, is listed. 
(Talking about books here; hyperlinking can do the job, too, of course.)

-michael