Re: How to document a programming language?

[<neilson -at- windstream -dot- net>]

There are essentially two parts to documenting a computer language. The first part, often initially constructed in an esoteric or incredibly concise fashion by the creator of the language, is a reference manual. It answers the question, "What are the parts of the language and how are they legally put together?" The second is the "language user's manual" and it (if properly done) addresses the problems to be solved. Both are hard to write, but the former is easier to get reviewed. The latter may suffer from incompleteness merely because it lacks examples that no one's thought of yet.

It's helpful to make the reference manual match a standard format that's easily used by the programmers who will be using it. It's not necessary that you understand every nook and cranny of the language to do this.

Writing the user's manual requires direct assistance of a programmer who understands how to get good results from the language, and who is willing to prepare examples, and perhaps to help you write some. When in the course of writing examples you discover pitfalls (e.g., "never use variables beginning with underscore (_) outside of a macro definition; the compiler will crash with no error message...") that weren't addressed in the language spec or the reference manual, by all means put them in. There *will* be a lot of them. If you don't find any, you've missed them.

In most situations there is not enough time to write both manuals and to do them well. In retrospect, as you hear the users grumble about the insufficiencies of the reference manual and the non-existence of the user's manual, make notes for a future project.
--Peter Neilson


An entity who calls itself <technical writing plus> suggests: 

> Some of the most important questions in your mind, as you write and assemble
> the documentation, ought to be 'who am I writing to?' and 'why?'.
> 
> -----Original Message-----
> 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. 
> 
> I'd appreciate a pointer or two :-)


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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 &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: 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.