Re: Documenting a Programming Language

["Susan W. Gallagher" <sgallagher -at- expersoft -dot- com>]

At 01:22 PM 12/28/99 -0500, Megan Golding wrote:
>I am working on a document for a programming language...
>
>I need to document every detail of this language and at
>the same time draw attention to the more common functions.
>
>The format... is in two parts:
>1) complete list of functions and keywords sorted by the "type" ...
>2) examples sorted by increasing complexity...
>
>My questions:
>1) Given the huge gap in experience of my readers,
>what sort of content would you recommend I place in
>a "Getting Started" type of chapter? Or, can I assume
>that a person with reasonable intelligence can read
>the many full-length examples and "figure things
>out" (avoiding the "Getting Started" chapter alltogether).

If you can assume anything, it's that the user doesn't want to
read anything, never mind the _many_ explanations of _full-length_ 
examples. <g>

That said, there's a lot to be said for "hello world" -- a perfect
"getting startled" example if ever there was one. The classic "hello
world" example demonstrates the bare minimum required of the programmer
to get a program written and built and up and running. The result, the
words "hello world" emblazoned across the screen, prove that the software
is installed correctly and that the "application" can communicate with the
outside world. Programmers of all experience levels will work through "hello
world" to "get their feet wet" with the new language.

>2) I need to document every function and keyword
>in the prog. language. Do you suggest I sort based
>on the "type" of function or just give an alphabetical
>listing?

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.

HTH


-Sue Gallagher               http://pw1.netcom.com/~gscale/susanwg/
sgallagher -at- expersoft -dot- com     http://www.expersoft.com

The _Guide_ is definitive.
Reality is frequently inaccurate.  --Douglas Adams