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: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:
SCENARIO 1:
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.
SCENARIO 2:
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
reference.
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
http:\\www.spectrumsignal.com
"no matter where you go..... there you are." -- Buckaroo Banzai
