Here are the steps I go through when adding a language to
the dictionary. (Note that, to preserve consistency, other folks are not
encouraged to try to add entries. However, this status is negotiable.)
- Check my local list of about 140 languages to see which ones
I haven't worked on yet. Entries on the list are links with the
special CGI parameters that cause the back-end CGI to generate an
add form.
- Once the add form appears, I pop up another browser window and
check out a basic list of WWW resources for that language under
Yahoo:Programming Languages.
- I set the language type: A, C, D, F, L, M, O, P, S, or T.
- If the language is a subset, dialect, or variation of
some other major language, I put that name of that language
in as a cross-reference.
- I try to find a logo or distinctive image for that language,
possibly from a major vendor or university project. Some languages,
like Ada, that's an easy job, others just don't have a logo.
- Next, I try to find a primary reference web site for the language.
Sometimes this isn't possible, but usually something is available.
If the language is owned by a single organization, like Ada or
PostScript, then that site goes here. This is the link for
the language name itself.
- Then comes the big job, writing the description. First, I
look through my programming books and magazines, as well as
on-line tutorial sites. If necessary, I download a free
implementation of the language and skim some of the
documentation. The description normally contains
a list of features the language provides, maybe a little
background or history, what the language is used for,
and status of availability for implementations.
- As part of writing the description, I fill in the
origin field. The origin usually has a name or two,
as well the years that seminal initial work on the
language was done.
- Very few computer languages arise in isolation,
so I fill in some related languages next. The
back-end CGI automatically turns these into cross-reference
links.
- Next, I try to fill in the remarks and links fields.
The remarks field usually contains additional
background, subjective opinions, and comparisons
with other languages.
Each language gets to bear up to five extra WWW links.
I usually try to have at least one of each of the
following kinds: an FAQ, a commercial vendor,
and a tutorial.
-
I fill in the code example section. Just under
half of the code examples I write myself, and the
rest are adapted from books or web sites. I always
give some attribution on any example I copy.
- Last, I submit the entry and check its appearance
in the dictionary output format. Some proofreading
gets done at this stage.
- Later on, I do some additional proof-reading of
the entries. This stage needs more discipline.
The Perl CGI used for this programming language dictionary
is general-purpose, it can be used for any alphabetically-sorted
flat index of information (e.g. cat breeds, famous inventors, etc.).
The schema is controlled by a file residing at the server, and
HTML framework and decorations are supplied by templates HTML
fragments.