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?
