Re: Documenting a Programming Language. WAS:Syntax Diagrams

[Rebecca Phillips <Rebecca -at- QRONUS -dot- CO -dot- IL>]

Dear Jed:

My team also documents a programming language. We don't use any kinds of
diagrams to illustrate our syntax. In fact, I can't really imagine how
the diagrams would work, but that is probably just an indicator of my
limited imagination when it comes to anything beyond words.

Our language has very consistent syntax. Each command can take on
certain parameters, some optional and some required. In the
documentarian, we use square brackets to denote optional parameters. Any
parameter without square brackets is mandatory. Under each command, we
give the syntax, a table-like list of each parameter's meaning and its
legal values, a description of the command function, and an example.
There is no way we could document every single possibility for every
single command, but we do try to give examples that do something useful.

It is typical that you can't imagine all the possibilities your users
might need. If you could, you would have a GUI dialog box, not a
programming language. Incidentally, our application includes a GUI
dialog box that allows you to select a command. Once you select the
command, the box shows fields for each of the parameters relevant to
that command, so you don't have to type in the whole line yourself. This
is great for preventing syntax errors. You might consider suggesting
this kind of software improvement to the developers, particularly if
your audience is made up of novice programmers.

Regarding documenting of conditional loops, we don't document this as
part of the language commands. Rather, we include a preliminary chapter
on how to use the programming language. This gives explanations of what
a loop is, what conditional statements are available, how to use
mathematical operators, and other standard functions. We also tell the
user that the loop commands are the same as the ones used in the C
programming language, so anyone who knows C can just skip this chapter.
Again, this is part of the application itself. The developers had the
foresight to make our language as similar as possible to a popular
language so it would be easy to learn.

Also, we start with the assumption that the user has to know something
about programming. For us, this is a reasonable assumption, because our
product is designed for Software Quality Assurance (testing). If you
really need to teach the person programming, you probably need to add
several chapters of tutorials to the beginning of the manual, including
some sample programs the person can write and try out, just like any
other beginning programming manual. Think about how to empower your
users to understand the language, rather than having them copy commands
out of the book.

If many of your users are programmers, they probably just read the
syntax, anyway. I haven't noticed that programmers care a whit about
diagrams or long explanations. They read the syntax and try it out
before they RTFM. The best thing for these kinds of users is a "Quick
Reference Guide" which includes all commands, syntax and a one-line
explanation of the command.

Finally, context-sensitive help is a major plus for documenting this
kind of language. Since the person can only use the language when they
are sitting at the terminal, on-line help is critical. In on-line help,
using a lot of diagrams is going to bog you down.

Good luck.

Rebecca

Rebecca M. Phillips
Documentation Manager
Qronus Interactive Ltd.
Automated System Testing
http://www.qronus-int.com
rebecca -at- qronus -dot- co -dot- il