Re: How to document a programming language?

Subject: Re: How to document a programming language?
From: John Garison <john -at- garisons -dot- com>
To: Sarah Bouchier <Sarah -dot- Bouchier -at- exony -dot- com>
Date: Thu, 08 Mar 2007 12:03:08 -0500

It's been a while - the last programming language I documented was a
Pascal to Assembler conversion back in '79 (shades of the Old PC
technology thread ...), but I don't think that things have changed all
that much.

Generally, you need two sections: concepts and commands. The Concepts
section explains all the things you have to know, organized by whatever
scheme makes sense to use. The Commands section lists commands in
alphabetical order, preferably grouped by some rationale (I/O,
processing, printing, arithmetic, logical, whatever ...). Each command
should follow the same sort of structured format: Name, Definition,
Functional Description, Syntax, Example, Notes ...

You're on the right track. Just keep in mind the basics of tech writing
- that it has to be easy to find and accurate one you find it - and
you'll be fine.

My 2¢,

John G

Sarah Bouchier wrote:
> I've been documenting software for a good few years now, and I know how
> to do that; but I'm now looking at documenting QA's test harness, and to
> be honest I haven't the faintest clue where to start.
> I could do a basic 'these are the commands, this is what they do, here
> are some examples' but the commands are in some ways the least of it;
> the default values the test harness assumes are also very important, and
> there are a number of cunning little tweaks the QA manager has put in
> that are highly non-intuitive.

Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output.

Now shipping: Help &amp; Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help &amp; Manual:

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

How to document a programming language?: From: Sarah Bouchier

Previous by Author: Re: Old PC Technology
Next by Author: Re: The good old days.
Previous by Thread: How to document a programming language?
Next by Thread: Re: How to document a programming language?

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

Sponsored Ads