[erlang-questions] Erlang documentation cleanup (PREV: R13B01 modules, quick reference)

[Fred Hebert (MononcQc)]

On Tue, Aug 11, 2009 at 2:31 AM, Mazen Harake
<mazen.harake@REDACTED> wrote:
>
> This brings up a subject I've been meaning to bring up for a while. The online documentation needs modernisation... A few things that come to mind are:
>
> * Proper documentation search (please don't insult this by saying Google... that's just stupid)
I think this would depend on how we expect people to search:
There is the http://erlapi.prepor.ru/docs/ approach, which is good if
you know the module or function you're looking for. The problem with
this way of searching is that while it helps those who know the
modules, if you're looking for a simple concept like "list length",
you won't find anything (even the python search doesn't do this too
well). Google is usually the best way to search docs that way, though.
Providing two ways to search could please both 'old-timers' and
newcomers.

> * Function overview in each module
> * Module summary on the modules page (and categorized) much like http://docs.python.org/3.1/library/index.html
> * Add anchors to the HTML so that a link can go straight to a function
> * Make HTML XHTML
Agreeing with each of these.
Anchors would be useful; to reuse the 'list length' example; if the
search engine pointed you to the 'length' function from the 'erlang'
module, it would be a [minor] pain to have to scroll down to the
function definition.
HTML as XHTML would also make things easier to "scrape" with a normal
XML parser, which is not bad.

> * More visually appealing. Probably this won't go very well with old-timers but frankly I have spoken to beginners in Erlang that say that when looking at the documentation it looks like something created 20 years ago and it doesn't look very... well... "appealing". The fact they are right about the age is not the point now is it ;) ?

I believe that before that, managing to get rid of frames would be
better: frames are indeed outdated, and although somewhat practical in
an indexed navigation (maybe just within a single module), they are
annoying because you can't intuitively link them to other people
without losing context.

I believe usability should come before beauty when talking about
technical and formal documentation. An example of nice things to have
would include links to other modules when they are mentioned and
anchors for 'global' types in function signatures. Take the io:read/3
function as an example: http://erlang.org/doc/man/io.html#read/3

The io_device() type is defined on top of the page, but assuming
you're coming from an anchor to the function, the type won't mean much
to the reader. Most people, rather than scrolling up, would probably
start a new search to find what 'io_device()' is about. Adding an
internal anchor of the kind io.html#type-io_device could probably fix
that. Then when the function 'file:open/2' is mentioned, no link is
provided. The user is expected to go through the URLs or a new search
to follow documentation. In ideal circumstances, reading the
documentation should require no effort past trying to understand what
is written.

I believe the Erlang doc is very thorough and has lots of details, but
is mainly opaque to new users and a disaster in usability. The effort
deployed at http://erlapi.prepor.ru/docs/ is already an impressive
amelioration and makes searching through the docs 10 times easier
(thanks to Andrew Rudenko).

>
> Probably many more issues exist.... just saying.
>
> /Mazen
>
> ________________________________________________________________
> erlang-questions mailing list. See http://www.erlang.org/faq.html
> erlang-questions (at) erlang.org
>