RE: Documenting a Programming Language

["Geoff Lane" <geoff -at- gjctech -dot- co -dot- uk>]

Susan W. Gallagher wrote:
>
> I've tried the "sorted by function" routine before and my users
> *hated* it; they said it was impossible to find anything. And, in
> retrospect, I understand why. Sorting according to function vs.
> sorting alphabetically is akin to finding something in the TOC vs.
> finding something in the index. When you sort by function, the user
> needs to be clued in to the way you think about arranging things.
> And face it, they aren't. The alphabet, OTOH, is the alphabet, and
> users will instantly be clued in to your scheme. There's a lot to
> be said for that. So, if you do choose to sort by function, supply
> a cross-referenced alpha list as well.
----

A cross-referenced, alpha list? I tend to rely on the index for that and
normally document functions grouped by category (for example, string
functions, type conversion functions) and then alphabetically within each
category. However, I always include an paragraph or two at the top of the
function reference section to explain how I've ordered that section. As a
developer, I hate purely alphabetical ordering of function definitions. The
names of the functions in some languages are not obvious (for example, what
do you call a function that casts a string representation of a date to a
proper date? CDate, ToDate, StrToDate, something else?) and finding that
elusive function sometimes can take *hours* when the reference is ordered
alphabetically.  For this example, knowing that there is a type conversion
category narrows the search somewhat.

No matter how you arrange the function definitions, a really good index is
essential. The indexer has to think like a programmer. The language that
you're documenting is probably not the first language that the readers have
used. Thus, they will search for functions using the name of a similar
function from a language with which they are familiar -- so including these
'foreign' function names in the index can significantly help your readers.

FWIW, I feel uneasy about creating a programmer's reference that doesn't
include a BNF definition or 'railroad diagram' or two. You can define both
procedural and declarative languages this way, and both definition methods
are concise and unambiguous.

The 'hello world' example is a must. As others have written, this enables
the reader to test the programming environment and to go through the
mechanics of delivering a program without worrying too much about syntax and
semantics.

Try to keep examples simple while demonstrating enough of the function,
method, procedure et al. to make the example of use to the reader. For
example, if the function has optional parameters, then the example should
demonstrate at least one of them.

Just my two eurocents,

Geoff Lane
Cornwall, UK
geoff -at- gjctech -dot- co -dot- uk