[erlang-questions] Erlang documentation -- a modest proposal

[Andrew Berman]

I'm sure some of you will disagree, but I've always found the Java SE docs
to be easy to use and useful: https://docs.oracle.com/javase/8/docs/api/

Couple reasons why:

   1. The class list on the left doesn't move when I scroll on the right.
   I'd say this is a must with any documentation.  Erlang docs already do
   this, but I'd like to just point out how essential it is.

   2. When you click a class, you get a nice, detailed class description at
   the top, then you get a summary of all the methods.  I think this summary
   is something that would be very useful for Erlang docs.  Most of the time I
   don't need to see all the details of an Erlang function, I just need to
   know of its existence, briefly what it does, and what it takes in and spits
   out.  This sort of summary is great for that.  And when I do need more
   in-depth info, I can click the function name and it takes me right to it.

   3. I like how everything is clearly sectioned off.  Each method in the
   docs has its own box, each section is clearly defined, etc.  This goes
   to Loïc's point of indentation.  By sectioning off the methods, it makes
   things very readable.  I can scroll down and immediately know what method
   I'm on and what the text below it refers to no matter where I am in the doc.

   4. Everything is hyperlinked.  If there is a class referenced, it's
   hyperlinked so I can go and visit that class very easily.  Again, Erlang
   docs pretty much do this as well, but I'd imagine there are places where it
   can be expanded.

--Andrew

On Tue, Sep 27, 2016 at 5:06 AM Loïc Hoguin <essen@REDACTED> wrote:

> On 09/27/2016 01:13 PM, Kenneth Lundin wrote:
> > On Tue, Sep 27, 2016 at 11:46 AM, Joe Armstrong <erlang@REDACTED
> > <mailto:erlang@REDACTED>> wrote:
> >
> >     Re: HTML
> >
> >     I'd very much like to mock up a "nice" HTML display of the functions
> >     in a module.
> >
> >
> > Have you looked at the Elixir doc for
> > example http://elixir-lang.org/docs/stable/elixir/Kernel.html?
> > I think the layout and function is quite good and the handling of css
> > and javascript is from what I can understand
> > handled nicely.
> >
> > For an application and modules they present pretty much the same as we
> > do today.
> > For sure the Elixir community have more cometence around html, css,
> > javascript than at least we on the OTP team have.
>
> I have no doubt they are better at HTML, CSS and JS, but they are not
> good at layout and styling IMO.
>
> The lack of indentation alone makes the Elixir documentation unreadable.
> Where do the functions start and end? This is much easier to figure out
> in the Erlang documentation.
>
> The huge vertical spacing everywhere makes it so that only about one
> function and a half gets displayed on my screen at a time for equivalent
> amount of information. The Erlang documentation has the double, 3 or 4
> functions.
>
> For some reason all the specs and code examples have a bottom scrollbar
> here even when no scrolling can be done.
>
> And in case you wonder, it's also unreadable from lynx. This time,
> function names and code examples are indistinguishable.
>
> The list of functions at the top is not very useful overall; the list of
> functions on the left is better but in the case of Elixir when I click
> "Functions" it scrolls the page for some reason; if I wanted to stay
> where I was and just take a quick look if a function exists, there goes
> my browsing. It also breaks the back/forward buttons for me (bad!). Not
> to mention it's not clear that you can expand it.
>
> The search result page also gets on top of the documentation you are
> currently reading. Impractical.
>
> The Elixir layout still needs a *lot* of work to be really usable. Not
> to say the Erlang documentation is "the best", but what it needs the
> most is a few tweaks (make it easy to reach every part of the
> documentation from http://erlang.org/doc/) and more content. It's
> already very good, in all its output formats. This would be a huge step
> backward.
>
> I also have some concerns with the main Elixir site; the font and font
> size make it hard to read. At least they got the font right in the
> function reference.
>
> (If you worked on the Elixir documentation don't take this personally. I
> have the same amount of criticism over my own, if not more.)
>
> --
> Loïc Hoguin
> http://ninenines.eu
> Author of The Erlanger Playbook,
> A book about software development using Erlang
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160927/53c149fd/attachment.htm>