Documenting a Programming Language

Subject: Documenting a Programming Language
From: "Megan Golding" <megan -dot- golding -at- dvtsensors -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 28 Dec 1999 13:22:27 -0500

I am working on a document for a programming language our
software developers have created. The audience for this
document is mainly engineers who are already familiar
with some form of PC-based programming. There are,
however, some who'll be reading who've never programmed
before. The latter group is a small minority -- no more
than 10-15% of the audience.

When I started documenting this prog. language, I followed
the flow of the _Visual Basic for Dummies_ book. However,
the question, "Yeah, but where is that documented?" comes
up quite a bit. I am forced to answer, "That isn't documented
here."

I need to document every detail of this language and at
the same time draw attention to the more common functions.

The format I've settled on (for now) is in two parts:
1) complete list of functions and keywords
sorted by the "type" of function (math, logical, etc.)
2) examples
sorted by increasing complexity, an introduction of
the application, and a "blow by blow" explanation
of the code in paragraphs following the example

My questions:
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? 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).
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?
3) Can you recommend some good references (both on-line
and on paper)

I thank everyone in advance for any assistance you can
provide me!

Regards,
Megan Golding
DVT Corporation
mailto:megan -dot- golding -at- dvtsensors -dot- com





Previous by Author: RE: What department are you in?
Next by Author: RE: accents and umlauts
Previous by Thread: Re: [pub-forum] grammar question
Next by Thread: RE: Documenting a Programming Language


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

Sponsored Ads


Sponsored Ads