Re: Documenting a Programming Language

Subject: Re: Documenting a Programming Language
From: Sandy Harris <sharris -at- dkl -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 29 Dec 1999 09:21:49 -0500

Megan Golding wrote:

> I am working on a document for a programming language our
> software developers have created. ...

Have a look at Kernighan & Ritchie "The C Programming
Language". Clear, straightforward (at least for those
with some programming background), far superior to most
of the later publications on C.

Talk to your developers about what this is based on or
derived from. e.g. If it is a LISP descendant, you
should be looking at LISP books, stealing concepts
and examples wholesale, and perhaps referring readers
to those books.

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

Start with a really simple example, such as K&R's
"hello, world", that does nothing except produce some
visible output. That lets them know the language system
is installed right, and gets them past basic things
like editing a source file, compiling, running the
resulting program, ...
(Or other basics for an interpreted language.)

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

I'd try to do it with a progression of examples, by topic.

Looping, function calls, simple data types, building more
complex types, ... Discussion and short examples for each.

> 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'd use straight alphabetical for fast look-up, with lots
of links. e.g. example section on loops includes a list of
all looping constructs. An extra index lists functions by

If possible, I'd also include a formal spec for the language
in BNF or some similar notation.

> 3) Can you recommend some good references (both on-line
> and on paper)

Grab a copy of Linux, FreeBSD, NetBSD or OpenBSD. Any of
those will include a half dozen programming languages.
At least C, C++, several shells, awk and Perl. Likely a
couple of variants of LISP, Python, Pascal, Fortran, ...
This will give you a range of languages and documentation
approaches to look at.

Previous by Author: Re: What's Telecom?
Next by Author: Re: Contracting, Contracting
Previous by Thread: Re: Documenting a Programming Language
Next by Thread: Re: Documenting a Programming Language

What this post helpful? Share it with friends and colleagues:

Sponsored Ads