RE: Documenting a Programming Language

Subject: RE: Documenting a Programming Language
From: Dave Neufeld <Dave_Neufeld -at- spectrumsignal -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 30 Dec 1999 11:32:07 -0800

Most of the responses to this thread prefer alphabetical ordering
over than categorical listing. I strongly agree, but encourage the use of a
secondary, simple categorical grouping as well. Here's why.

Alphabetical ordering is objective, while categorical listing is
subjective. Different authors and readers have different ideas of what
categories are needed while everyone (within reason) knows how order items
alphabetically. Generally, all authors will create the same ordering when
sorting alphabetically, but categorical listings will be different for each
author based on the author's perception and bias.

Another difference between alphabetical ordering and categorical
listing is that alphabetical ordering has one entry per item; no more and no
less. In categorical listings, an item (in this case an API function) may
apply to several categories, or even to none at all!

This is why alphabetical listing should be the primary sorting
order. But categorical listing still has an important purpose. In essence,
comparing alphabetical ordering and categorical listings are bit like
comparing apples and oranges. They each have different uses; just like PDF
and HTML.

So, where does the user need the alphabetical ordering and where do
they need the categorical listing? Here's two scenarios:

Bob is writing some code and needs to do a certain task. He figures
there must be a function to do this, but how does he find it? In this case a
categorical listing is used. All this categorical listing does is point him
to the correct function name, which he then looks up in the alphabetically
ordered function reference. To make things convenient, this function may be
listed under several categories, which is only really possible if the
categorical listing merely points the reader to the function to be looked up
in the alphabetical ordering of functions.

Mary has just been hired to help Bob with his code. As she looks at
the code she tries to figure out what the functions do. To do this she looks
up the functions she is curious about in the alphabetically ordered function

IMO I feel that the second scenario happens more frequently than the
first. The first scenario happens initially when looking for a particular
functions, but the second scenario happens many times after that as
developers reference the information needed to use the function.

In API documentation that I've liked, functions definitions are
organized alphabetically but have a concise categorical listing that
precedes the alphabetical list. This categorical listing does not describe
the functions at all; it just lists functions in categorical groups. This
allows many categories to list many functions (sometimes several times) in a
very short space. Very simple and very quick.

David Neufeld
Technical Publications
Spectrum Signal Processing, Inc.
dave_neufeld -at- spectrumsignal -dot- com
"no matter where you go..... there you are." -- Buckaroo Banzai

Previous by Author: RE: Total Waste of Time
Next by Author: STC Exemplar nominations
Previous by Thread: RE: Documenting a Programming Language
Next by Thread: So Many Educational Choices... (kinda long)

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

Sponsored Ads