I like examples. A salient example for me is the InterLISP-D manual. Back in the mid to late 1980s I loved it.
I read it cover to cover, and learned everything I needed to know from it. Two days after first reading the
(two!) chapters on graphics, I was able to code up a multi-panel debugger for the software I was working on.
(I have never since found anything as straightforward.) Now that I it installed on my Linux box, I find the
same documentation unattractive, awkward, and frustrating.
What has changed? My typographical taste certainly has. The text is indented far from the left margin and I do not like that. There is heavy use of horizontal rules in tables of contents, and something much visually lighter would be easier to read. But there are structural issues. Itās not until page 163 that we see a function definition and not until page 171 that we learn what the form actually does. These days I want more examples. Because the most important change is the way I want to use the documentation. Iām not reading from cover to cover trying to learn everything. Iām trying to answer the question āhow do I do THISā.
This leads me to a problem I have with Erlangās stdlib. There are too many I/O modules and I can never remember which one I need to read the documentation of. Has anyone considered tool support for āunion documentsā which let you distribute implementations across several modules for information hiding/maintenance purposes, but put the documentation in a single topically organised file?
Another lesson from the InterLISP-D example is that different users have different needs.
We should, for example, consider the needs of the approximately 10% of male readers who have some degree of colour-blindness.
We should also consider the needs of people reading the documentation using some form of text-to-speech system.
ALL the information should be accessible through the plain text.
But people have different information-accessing needs. Some people want to learn how to use an application (in the Erlang
sense). Some people need to read the overview of a module (possibly a union of modules). Some people need to see some examples of using a particular function. Some need clarity on a type, and want to know whatās in the type and what functions work with it. Some need to follow a topic which is neither a function nor a type nor a module. Some need to see lots of examples. Some will be annoyed by them.
Thereās a book I got several decades ago. The title is āProgramming as if People Mattered: Friendly Programs, Software Engineering, and Other Noble Delusionsā. My copy is >1000km away so if I recall correctly this is the book that described an experiment done when it first became possible to display fancy styled text on a computer screen. The conditions were (existing text vs improved text) x (plain display vs styled display). The result was that users obtained no benefit from the styled display, whereas improving the text reduced the time it took to solve their problems. On the other hand, users liked the styled text better.
So a poll of users might well result in a preference for fancy styled text that they canāt actually read very well.
Itās important to ask āwhat is the PURPOSE of this documentation system?ā Is it to pound oneās chest and say ālookit whut I can do!ā
Is it to say āhey, weāre hip with the latest cool fashionsā? Is it to help people accomplish tasks, and if so, what people and what tasks?
I shall always be grateful for some lessons Kennita Watson (lead technical writer at Quintus for several years) taught me:
(1) engineers should not be allowed to write user documentation ā they know too much
(2) the table of contents and indices are also documentation. Index, index, INDEX!
(3) there should be examples
(4) the examples MUST work
(5) if the documentation and the code disagree, one of them is wrong, and probably both are.
Free text search can to some extent substitute for indexing, but itās a poor substitute.
() It puts words in the examples on the same level as words in the explanations.
() It finds words, not concept. You can put a concept in the index even if the word isnāt on the page.
Personal exampleā¦ I am resurrecting an old AI programming language. Writing the emulator is fairly straightforward.
Writing the library has been straightforward and educational ā the language was capable of far more than I realised
at the time. Writing the compiler has been exceedingly tricky because I am working from documentation and it was
very inadequate on the scope rules. I donāt actually have a manual for the dialect I particularly wanted to
reconstruct because all surviving ones were accidentally destroyed in a fire. I do have several other manuals,
but while the authors were all good at writing clear prose (better than me), they KNEW what the scope rules were
and the only way that the later manuals help is by pointing out that what the old manual DID say was wrong and no
implementation ever did what it said. My current attempt at documenting the scope rules is my third, and when
Iām done Iāll finally be able to finish the compiler. (Whatās particularly annoying is that my old University had
a listing of the original compiler, which they have since lost.) I have a useful amount of old code, but none of it
goes anywhere near the corner casesā¦
Do I need to point out that fancy styling would be of no help to me at all?
Do I need to point out that this perfectly exemplifies Kennitaās āengineers should not be allowed to write documentation ā they know too muchā?
Do I need to point out that āscopeā is not a keyword in the language, nor the name of a function or a type or a module, but that I needed to find everything I could about it in the manuals? If you want an Erlang example, searching for ālifetimeā took me to the debugger, not the language (lifetime of a variable) or a network module (lifetime of a connection). Keyword search has its limitations.
So. If you want to propose a new documentation system for Erlang, how about one that makes it easy to generate a concept index for a module? Iāve got cmark and hxindex, but having to write lots of and elements kind of defeats the point of Markdown, no?
