[erlang-questions] yet more ranting about Erlang docs

[Joe Armstrong]

On Wed, Feb 17, 2010 at 11:27 AM, Michael Turner <leap@REDACTED> wrote:
>
>
> 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?

Because the code that generated the web site didn't add a search
box.

The entire site is automatically generated from a large number of XML
files. This set of files started off as SGML has migrated to XML and
has been formatted via LaTeX and FOP.

When we make a new site, or new formatting we try to be very careful
not to break old stuff and to phase out stuff that is not used
and phase in new stuff - this takes a while.

Not having search boxes everywhere - like dead links - is a bug
(or a symptom of an underlying problem).

About 18 months ago all the documentation was marked up in
SGML and not released. The last 18 months efforts was as follows:

    - change the markup to XML
    - the PDF generator from LaTeX to FOP
    - piff up the HTML

Subject to the condition "don't break the documention system"

So now it's published and gitted and in XML and we can start polishing
the rendering engines - adding searches or whatever.

Taking out internal SGML and turning it into XML without breaking
everything has been top priority - not rendering.

>
>>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.

Marketing airhead - no. The only marketing people just tried to sell
Erlang - they had no influence on the terminology.

"Application" was just a name for a "directory with stuff in it" that
obeyed certain principles. Things inside an application could be
started and stopped, code in an application could be changed and so
on. Most applications were active (things like databases, web servers
etc) - some were pure code (stdlib) - the pure code directories (about
5% of the total) were anomalies - so we shoe-horned them into
applications - to make everything consistent. A bit silly because
you can't stop and start a library, but you can code_change it :-)

 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?

No idea - personally I find most language websites pretty
incomprehensible - I have never found leaning any new language
a pain-free process - I have spent most of my working life staring
at strange error messages wondering what they mean.

If you're put off by strange terms, lousy documentation, incorrect
examples, code that doesn't work, explanations that are plain wrong
and idiotic specifications you shouldn't be a programmer.

In my book a "smart programmer" is one who despite these minor
obstacles can figure out how things work.

Would you hire a "smart programmer" who rejected a language
because the documentation was crap?

One sign of a smart programmer is that they recognize that the
documentation *is* crap.

If I found a programmer who said "this documentation is great"
I would be really suspicious - don't hire this guy :-)

Sounds like you're a smart programmer, having found the odd
inconsequential wart in our otherwise incomparably magnificent documentation.

Cheers

/Joe

>
> -michael turner
>
>
>
>
>
>
> ________________________________________________________________
> erlang-questions (at) erlang.org mailing list.
> See http://www.erlang.org/faq.html
> To unsubscribe; mailto:erlang-questions-unsubscribe@REDACTED
>
>