[erlang-questions] yet more ranting about Erlang docs

[Dale Harvey]

the otp team are working on a site with a global side search navigation
http://demo.erlang.org/erldoc?q=test&x=0&y=0

and (again) for a purely function reference
http://erldocs.com/R13B03/stdlib/lists.html?search=lists:a&i=0#all/2
also has a global side search

I dont think anything outside Erickson official is non sequiter, while most
language have some form of standards bodies, the tools / tutorials
surrounding them are often community driven, rubys community in particular
is great at this.

I recommend learners to either buy the orielly / joes book, or visit
http://learnyousomeerlang.com/content well before visiting erlang.org, while
these learning/documentation tool might be missed by people visiting
erlang.org there is no reason for them not to become the defacto tools,

Bjorn / Erickson are doing a great job accepting patches and changes and it
looks like lots of work is going into the new site, and I see no reason to
think that Erickson wouldnt link out to great tutorials and tools if the
community produced them, in fact the new site looks like that is an aim.

Cheers
Dale

On 17 February 2010 10:27, Michael Turner <leap@REDACTED> wrote:

>
>
> On 2/17/2010, "Bob Ippolito" <bob@REDACTED> wrote:
>
> >On Wed, Feb 17, 2010 at 12:35 AM, Dave Peticolas <dave@REDACTED> wrote:
> >> 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
> >
> >http://erlang.org/doc/man_index.html
> >
> >It's the "Modules" hyperlink in the left frame of the docs.
>
> In the left frame of what pages?  Only at http://erlang.org/docs?
>
> I wondered where this page was linked from (who knows? maybe some place
> that was intuitively obvious? you can't rule it out), so I clicked on
> "Up".
>
> Dead link.
>
> (The link next to it is labeled "Erlang", which at that point is like
> being in San Francisco and seeing a sign saying, "California".)
>
> And when you get to the module list, it describes itself not as a module
> list, but as "Manual Page Index".  Not exactly the same thing.
>
> There are some navigation, nomenclature and comprehension issues here.
>
> >To be fair, it's not that obvious to find,
>
> I've run across it before.  But you shouldn't have to "run across"
> it.  It should be linked from sidebars on every page.  (And not all
> pages have a handy sidebar.  E.g., the otherwise-relatively-helpful
> Applications list, for some reason:
> http://erlang.org/doc/applications.html.)
>
> Side-rant: Why isn't there a search box on EVERY PAGE?
>
> >The biggest problem with the Erlang module index is that it has no
> >context whatsoever about what the modules do (other than the
> >semi-arbitrary application they belong to), so if you don't know at
> >least part of the name already you won't be able to search for the
> >module you want on that page.
>
> "Semi-arbitrary application" -- well, OK, maybe Erlang/OTP defines the
> term "application" somewhere, carrying a sense with which I'm not
> familiar, somehow justifying the description of certain libraries as
> applications?
>
> Ah, here it is: http://erlang.org/doc/man/STDLIB_app.html
>
> "In OTP, application denotes a component implementing some specific
> functionality, that can be started and stopped as a unit, and which can
> be re-used in other systems as well."
>
> OK, fine.  C&S p.264 provide a roughly equivalent definition. So in what
> sense dpes STDLIB conform to these definitions?  Here's what we get
> from the reference manual:
>
> ----
> APPLICATION
>
> STDLIB
>
> APPLICATION SUMMARY
>
> The STDLIB Application
>
> DESCRIPTION
>
> The STDLIB is mandatory in the sense that the minimal system based on
> Erlang/OTP consists of Kernel and STDLIB. The STDLIB application
> contains no services.
> ----
>
> "No services" meaning that there's nothing to stop and start?  If so,
> why call STDLIB an "application" even in the Erlang sense?  It's
> bizarre enough to me that even Kernel is called an "application," but
> I *can* bend my brain around it.  A library that just sits there, though?
>
> I find myself wondering if there was a time, back when Ericsson was
> trying to commercialize Erlang, when some marketing airhead went nuts
> trying to get the word "application" used everywhere, perhaps because
> when he talked to Erlang programmers they all sounded dangerously
> theoretical to him.  Why, with STDLIB and some other libraries suddenly
> reclassified as "applications," he could talk about how the number of
> applications written in Erlang was growing by leaps and bounds!
>
> Cool languages attract smart programmers, and Erlang is cool.  But as the
> saying goes, you only get one chance to make a first impression.  How
> many smart programmers, drawn in by the buzz about Erlang, land at
> www.erlang.org, browse a little, feel puzzled by the strange use of
> terms, end up frustrated by difficulties in navigation, then maybe
> bookmark it but never really come back?
>
> -michael turner
>
>
>
>
>
>
> ________________________________________________________________
> erlang-questions (at) erlang.org mailing list.
> See http://www.erlang.org/faq.html
> To unsubscribe; mailto:erlang-questions-unsubscribe@REDACTED
>
>