yet more ranting about Erlang docs

[Michael Turner]

On 2/17/2010, "Bob Ippolito" <bob@REDACTED> wrote:

>On Wed, Feb 17, 2010 at 12:35 AM, Dave Peticolas <dave@REDACTED> wrote:
>> I think a global module index, like the one for the built-in
>> Python modules, would be useful, both for quickly finding the
>> module you already know the name of, and for browsing to see
>> just what is available:
>>
>> http://docs.python.org/modindex.html
>
>http://erlang.org/doc/man_index.html
>
>It's the "Modules" hyperlink in the left frame of the docs.

In the left frame of what pages?  Only at http://erlang.org/docs?

I wondered where this page was linked from (who knows? maybe some place
that was intuitively obvious? you can't rule it out), so I clicked on
"Up".

Dead link.

(The link next to it is labeled "Erlang", which at that point is like
being in San Francisco and seeing a sign saying, "California".)

And when you get to the module list, it describes itself not as a module
list, but as "Manual Page Index".  Not exactly the same thing.

There are some navigation, nomenclature and comprehension issues here.

>To be fair, it's not that obvious to find, 

I've run across it before.  But you shouldn't have to "run across"
it.  It should be linked from sidebars on every page.  (And not all
pages have a handy sidebar.  E.g., the otherwise-relatively-helpful
Applications list, for some reason:
http://erlang.org/doc/applications.html.)

Side-rant: Why isn't there a search box on EVERY PAGE?

>The biggest problem with the Erlang module index is that it has no
>context whatsoever about what the modules do (other than the
>semi-arbitrary application they belong to), so if you don't know at
>least part of the name already you won't be able to search for the
>module you want on that page.

"Semi-arbitrary application" -- well, OK, maybe Erlang/OTP defines the
term "application" somewhere, carrying a sense with which I'm not
familiar, somehow justifying the description of certain libraries as
applications?

Ah, here it is: http://erlang.org/doc/man/STDLIB_app.html

"In OTP, application denotes a component implementing some specific
functionality, that can be started and stopped as a unit, and which can
be re-used in other systems as well."

OK, fine.  C&S p.264 provide a roughly equivalent definition. So in what
sense dpes STDLIB conform to these definitions?  Here's what we get
from the reference manual:

----
APPLICATION

STDLIB

APPLICATION SUMMARY

The STDLIB Application

DESCRIPTION

The STDLIB is mandatory in the sense that the minimal system based on
Erlang/OTP consists of Kernel and STDLIB. The STDLIB application
contains no services.
----

"No services" meaning that there's nothing to stop and start?  If so,
why call STDLIB an "application" even in the Erlang sense?  It's
bizarre enough to me that even Kernel is called an "application," but
I *can* bend my brain around it.  A library that just sits there, though?

I find myself wondering if there was a time, back when Ericsson was
trying to commercialize Erlang, when some marketing airhead went nuts
trying to get the word "application" used everywhere, perhaps because
when he talked to Erlang programmers they all sounded dangerously
theoretical to him.  Why, with STDLIB and some other libraries suddenly
reclassified as "applications," he could talk about how the number of
applications written in Erlang was growing by leaps and bounds!

Cool languages attract smart programmers, and Erlang is cool.  But as the
saying goes, you only get one chance to make a first impression.  How
many smart programmers, drawn in by the buzz about Erlang, land at
www.erlang.org, browse a little, feel puzzled by the strange use of
terms, end up frustrated by difficulties in navigation, then maybe
bookmark it but never really come back?

-michael turner