Re: How to document a programming language?

[John Garison <john -at- garisons -dot- com>]

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. http://www.DocToHelp.com/TechwrlList

Now shipping: Help & 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 & Manual: http://www.helpandmanual.com

---
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 http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


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
http://www.techwr-l.com/techwhirl/ for more resources and info.