Re: Documenting a Programming Language

["Steven J. Owens" <puff -at- netcom -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.

Susan W. Gallagher writes: 
> 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>

     Aigh!  No!  No no no no no.  I used to write programming language
and API documentation. One thing you want *tons* of is examples.
Explanations of the examples is a good idea.  Most programmers learn
by looking at code written by other programmers.  The added assist of
description of the code and how it works is a plus.  The big obstacle
here is getting good examples.  I'd recommend a multi-pronged approach
of short, quick code fragment examples in the reference section, with
more involved, fully fleshed out examples in the tutorial, complete
with problem, diagnosis, plan, implementation and source code.

     In general, provide a reference work (alphabetical listing of
functions and language elements), an overview work (statement syntax,
data structures, flow control structures, decision structures) and a
how-to-program tutorial.  You need all of them.  The overview will
help readers get a sense of the language and a handle on the topic,
and it will help experienced programmers get a jumpstart on the
language. In fact, I'd recommend that the overview's second chapter
should be a summary of "here are the syntaxes in BNF" and don't bother
explaining much of the details, followed by in-depth explanations of
what a statement is, what a flow control structure is, etc.


> That said, there's a lot to be said for "hello world" 

     "Hello world" is a traditional introduction to programming (I'm
not sure if Kernigan&Ritchie started it or just promulgated it in
their book).  As a program it's fairly minimal but it demonstrates
many of the basics - a fully functioning program that produces output.

> >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.

     Definitely document the functions alphabetically, but also
provide a categorized listing of the functions in one of the early
chapters.  Don't get too hung up on having each function occur only in
one category.  Essentially this is a specialized index of functions.
The idea here is, when the programmer wants to read in a file, the
function may be named something like "file", or it may be "open" or
"read" or "load" or whatever.  So have general categories of
programming tasks and which functions are applicable.

Steven J. Owens
puff -at- netcom -dot- com