RE: Documenting a Programming Language

Subject: RE: Documenting a Programming Language
From: "Humbird, Len - CFC" <Humbird -dot- Len -at- cfwy -dot- com>
To: "'TECHWR-L (E-mail)" <TECHWR-L -at- LISTS -dot- RAYCOMM -dot- COM>
Date: Tue, 28 Dec 1999 10:54:13 -0800

Perhaps what you could do is a combination of having a "getting started"
chapter, plus some "helpful hints" sprinkled in the margins. I've done this
with some smaller manuals and I am quite fond of the look. Though I am in
agreement with Mr. Plato's "throw every bit of info at them", I do as much
cross-referencing as possible. This makes it easier for the readers to find
what they're looking for.

My basic tendency in documenting is to assume that the reader is ramping up
on the info in the same way as I did when I was exposed to the project -
except with not so much hand-holding. Our brains are wired with associative
links. Our memory is based on association and chronology. So when I design a
document, I try to plan out a sequence of learning... foundational
knowledge, building blocks, step-by-step, and gradually get to some good
stuff. And along the way have some associative hints. Those "hints" might
also be known as marginal notes, and only work if you have a wide enough
page gutter.

This technique might not be appropriate for a technical reference like what
you're building, but it's perfectly appropriate for a beginner's guide.
Maybe that's what you should think of doing. And the more I think about it,
the better it sounds - to split your project into these two types of
documents. One is a dictionary of the language, the other is more like "Tom,
Dick and Jane go to programming school".


-----Original Message-----
From: Megan Golding [mailto:megan -dot- golding -at- dvtsensors -dot- com]
Sent: Tuesday, December 28, 1999 10:22 AM
Subject: Documenting a Programming Language

I am working on a document for a programming language our
software developers have created. [...]

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

Previous by Author: RE: Baseline Skillset for Technical Writers?
Next by Author: RE: to be versus ing - permutations galore!
Previous by Thread: Documenting a Programming Language
Next by Thread: Re: Documenting a Programming Language

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

Sponsored Ads

Sponsored Ads