[erlang-questions] Missing The Point Of Documentation

[Michael Turner]

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