[erlang-questions] Missing The Point Of Documentation
Wed Feb 17 06:35:15 CET 2010
Michael Turner wrote:
> On 2/16/2010, "Jayson Vantuyl" <kagato@REDACTED> wrote:
>> 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.
> Yes, it's truly annoying.
> Quick: arriving with fresh eyes, where would you expect stdlib to be
> 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
> 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
> 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:
Python also provides a more structured view of the same set:
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.
More information about the erlang-questions