[erlang-questions] erlang api documentation

[Richard A. O'Keefe]

I get so incredibly frustrated when asked to crawl through a vast
trackless forest of pages.  I want to sit in a comfortable chair
under a good light and read nice crisp high contrast text; on paper!
Electronically, I want stuff I can *search*.  That argues for having
stuff in *big* pages where searching can get some traction.  Then
there are times when I want to find just one thing, and R's on-line
help (or for that matter, SWI Prolog's) is perfect.

The key point is that there is no *one* form which will serve all
common uses well.  One thing which is NOT a good idea is stuffing
on-line documentation chock full of Javascript.  A reader should
*NEVER* have to enable security holes (whoops, Javascript) in order
to get usable links.

One very important thing, by the way, is to remember that people do
need to print pages, and that not everyone has the same size paper,
and not everyone has the same size screen.

A very very important thing about documentation is that the javadoc
approach tends to encourage a very atomised view of documentation.
Overviews, models, examples, templates, all sorts of stuff are not
information about the single methods that Javadoc tends to be good at.

Tree navigation tools are great for monkeys.  For humans, a good
information retrieval engine is at least as important and doesn't
wipe out so much potentially useful screen real estate.