Language documentation

[Francois-Rene Rideau <address@hidden>]

On Tue, Feb 18, 2003 at 07:33:33PM +0100, Herchenroeder, Thomas wrote:
> The point I found worthwhile in Kevin's posting was that a language, among
> other things, should be *useful*.
Well, of course! How clever of him! I would *never* have thought of that!
Thank you, Kevin! Let me kiss your feet, Thomas!

Seriously, though, that was not the point under discussion.

Kevin wants to use a programming language for a specific purpose:
munging text files.

He expects text file munging to be explained in the
f****ng first five chapters of the language manual.
He rejects the notion that string handling and file handling
be described later in the language manual, and is unable to even imagine
that they could be not documented in the language manual at all,
but be described into the library reference manual instead
(what? separating the language from a library? what's this notion?).
He considers that using a table of contents, or a library index,
or a search engine, or an interactive help facility, or a documentation
browser, is not for him, and that reading examples is out of the question.
And he doesn't want to read a document named "Using language FOO
for text file munging" -- no, he wants to read the godsend language manual,
and find answers to his domain specific questions immediately.

Obviously, what Kevin wants is a domain specific language for
text file munging. Well, perl is the perfect answer here.
I know of no other single language where text file munging is described
in the first five chapters of the manual.
Even the Python tutorial only discusses I/O in chapter 7,
and python has a library reference separate from any language manual,
if you want to look for specific string or file primitives.
Perl may not be _your_ and _my_ ideal language, but I'm sure it'll be Kevin's
-- and he'll find that though it originally started as a DSL for text file
munging, it is capable of doing much more nowadays. Maybe he'll even get a few
clues as to what programming is about, as time goes by.

The perl language has all the features Kevin requested:
* small footprint executables -- #!/usr/bin/perl is your standard prefix.
* It has easy to do file I/O
* It has lots and lots of good documentation
* It has a shallow end and a deep end
* It's just designed to manipulate strings
* It has the best interface to the OS of any language bar C.
* File and text munging is described not just in the first five chapters of
 the manual, but right in the introduction of it!
I understand that some people in this list love to hate perl.
Well, maybe they can learn a few things from perl, too (know thy enemies).

Is there a lesson to be learned from Kevin?
Not much from Kevin himself. But I suppose at the meta-level, yes:
* Some people are too ignorant, stupid, lazy, or stubborn,
 or any combination thereof (I admit to sometimes be all of that myself, too)
 to use the table of contents, symbol index, search engine, documentation
 browser, etc., unless you hit them on the head with a clue-stick.
 So, include such a cluestick prominently in any introductory documentation
 to your language, including your language's web page, etc.
* More generally, have good meta-documentation.
 Some documentation is meant for people without programming experience.
 Some documentation is meant for people who already know how to program,
 and want things done quickly in a specific domain. etc.
 It's nice if a beginner can quickly find the documentation he needs.
* There's a whole world of research to be done on how to automate
 documentation building, and information finding about a programming language.
 Let's say I have an idea about something I want to be done in the language;
 has it already been done before? Where can I find code for that?
* One idea could be type-based search in the code library -- though
 the actual code in the library can have slightly/subtly different types.
* For meta-level code, I don't even have an idea as to how to index it
 properly. Apart from reading the entire boring manual from A to Z,
 or being hit with a cluestick, how will you discover such an arcane feature
 as define-setf-expander, the day you need it? And what about the standard
 library of macros in your language (what? you don't have one?)
* A lot people learn by example. I do, at least. So an example database,
 and/or a well organized code repository is often as crucial a part
 of the documentation as a formal reference manual.
* Tutorials, HOWTOs and domain-specific documentation can bridge
 the gap between examples and reference manuals.
 You don't have to write them at first, but let them grow from the user
 community as the need arises.
* Ultimately, the ultimate documentation is the user community.

The conclusion of this is that the human aspect is important,
not just the technical aspect.
But we knew that already (didn't we?).
However, there's not much to *say* about the human aspect
-- though there's a lot to *do*.
And there's even less to *say* in a cross-language mailing-list.
So I expect discussion on this list to remain mainly on the technical aspect.

[ François-René ÐVB Rideau | Reflection&Cybernethics | http://fare.tunes.org ]
p[  TUNES project for a Free Reflective Computing System  | http://tunes.org  ]
As long as software is not free, we'll have hardware compatibility,
hence bad, expensive, hardware that has decades-long obsolete design