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: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
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.)
sorted by increasing complexity, an introduction of
the application, and a "blow by blow" explanation
of the code in paragraphs following the example
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
3) Can you recommend some good references (both on-line
and on paper)
I thank everyone in advance for any assistance you can