TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
type.
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.
