[erlang-questions] Missing The Point Of Documentation
Wed Feb 17 06:09:39 CET 2010
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
Operation & Maintenance Applications
Object Request Broker & IDL Applications
Interface and Communication 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?
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?"
More information about the erlang-questions