[erlang-questions] Missing The Point Of Documentation

[Dave Peticolas]

Michael Turner wrote:
> 
> On 2/16/2010, "Jayson Vantuyl" <kagato@REDACTED> wrote:
> [snip]
>> A fundamental problem with the Erlang docs is that they are very much
>> organized in a way that fits the invisible architecture underlying the
>> system, as opposed to being a helpful framework for communicating the
>> intent of the design.
> [snip]
> 
> Yes, it's truly annoying.
> 
> Quick: arriving with fresh eyes, where would you expect stdlib to be
> documented?
> 
>   Erlang/OTP System Documentation
>   Basic Applications
>   Database Applications
>   Operation & Maintenance Applications
>   Object Request Broker & IDL Applications
>   Interface and Communication Applications
>   Tool Applications
>   Applications Applications
> 
> (OK, I made up that last one.)
> 
> You chose "Erlang/OTP System Documentation", right?  Bzzt!  Fool! 
> It's under "Basic Applications".  (Whatever *that's* supposed to
> mean.)
> 
> I can't tell you how many times I've wanted to learn something about
> some Erlang standard library function, only to get lost online trying to
> find where the standard library is actually written up.
> 
> What does "Applications" mean in the above TOC?  Well, it mostly means
> "libraries", actually, not "applications".  Until you get to Tool
> Applications, which are applications (sort of) because they are more
> like programs to run.  Oh, except that the last entry in the sub-TOC for
> Tool Applications is ... "tools".  Implying that everything listed
> above it (appmon, common_test, etc.) is not a tool?  Well, that's been
> the pattern so far in the TOC: Applications are actually Libraries.
> 
> Someone once said, "A foolish consistency is the hobgoblin of small
> minds," and I agree.  But there's also such a thing as foolish
> INconsistency.  And this manual organization exemplifies it.
> 
> 
> How about the following, instead?
> 
>   Erlang/OTP Guide
>   Standard Libraries
>   Database & Maintenance
>   ORB & IDL
>   Interfaces & Communications
>   Tools
> 
> This is also wrong, I'm sure.  (Maybe ORB & IDL go under "Interfaces &
> Communications"?  Among other problems.)  But I think it's better.
> 
> You might say, "Well, here's what you're *supposed* to think when
> you're looking at the top-level TOC for the Reference Manual,"
> offering some explanation.  And there might actually be some method to
> this madness, for all I know.  But my eyes would glaze over immediately,
> and at the end of your spiel I'd reply, "Well, thank you very much,
> but why is *that* different from every other reference manual I've ever
> read and why aren't readers told at the beginning how *this* manual
> will be organized differently?"
> 
> -michael turner

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

Python also provides a more structured view of the same set:

   http://docs.python.org/library

Which is still easier than the Erlang version because the tree
is already fully expanded so you can search in the page. But I
always end up going to the global index.

dave