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

[Vlad Dumitrescu]

On Thu, Sep 29, 2016 at 1:28 AM, Richard A. O'Keefe <ok@REDACTED>
wrote:

>
> On 28/09/16 9:55 PM, Vlad Dumitrescu wrote:
> >>[I was very unhappy about the Elixir Kernel.html page.]
>
> I don't know what Kenneth wanted to highlight with the Elixir docs, but
>> I don't think that he meant the exact presentation.
>>
>
> He certainly praised "layout".
>

Yes, but layout (according to my understanding of the term) doesn't have
anything to do with use colors or fonts.
Just the placement in page.

I didn't find the structure especially helpful either.
> The distinction between types and functions and macros
> is an *IMPLEMENTOR*'s distinction, not a *USER*'s distinction.
>

I will comment here instead of below because the text is very long.

There are important and valuable things there to be noted and taken into
consideration, but most of them
are about the _content_ of the documentation.

What I can do right now, with relatively little effort, is take the current
sources and try to present
 them in a slightly better way, for some definition of 'better'. At the
moment, I only did a few small
changes, which I hope showed that improvement can be done even without
touching the sources.

Restructuring the whole documentation, adding marking to allow sorting and
indexing by different keys and
grouping by semantic relatedness, catering for both "beginner" and "expert"
users; all without
using javascript or any more advanced features (so that even browsers that
can't handle them
can be used) is a huge undertaking that is a task for the future.

Regarding how Joe is using the docs. How can one provide a static HTML that
is able to guess
which mode the user is in right now ('beginner' or 'expert')?

<bringing in a snippet from the end>
> HTML is great for when you have no idea what the user's
> screen resolution is, very little idea what fonts they
> have, how big their browser window is, whether they can
> discriminate colours (and in our fairly small department,
> two of my colleagues are red-green colour-blind, making
> many syntax colouring themes worse than useless for them),
> whether they can tolerate small text, ....

On the web, this is exactly the situation. We don't know anything about the
users' situation. At best, we can get statistics
about some of these things. What is different in our situation? What more
information do we have about the users? Except
that they are Erlang users, but that doesn't help much.

For typographically wonderful documentation, there is the PDF version. For
the web we can implement things that are impossible
with PDF, namely interactivity (sorting, grouping, filtering, theming), for
users that can and want to use a modern browser and
javascript. Otherwise one can target just one group at a time.

best regards,
Vlad


> Eiffel gets this right:  what is the distinction, *for a user*,
> between a named constant, a variable that is exported from a
> class (such variables can only be modified by the class's own
> code), and a feature (method) with no parameters?  There isn't
> any.
>
> What I need is
>  - an application or module overview
>  - a pointer to separate example modules or scripts (complete things)
>    test cases and maybe the source code
>  - a list of topics (table-of-contents)
>  - within topics
>    - an overview of the topic
>    - a pointer to examples (code fragments) relating to that topic
>      test cases and maybe the source code
>    - a list of subtopics (table-of-contents)
>    - within subtopics
>      - name
>      - syntax (type definition, function interface, &c)
>      - semantics (what the alternatives for a type mean, what
>        is the function supposed to compute)
>      - pragmatics (when did it become available, has it been
>        superseded and if so by what, are there any performance
>        or security issues I should know about)
>      - a pointer to examples and test cases and maybe the source code.
>
> The *last* thing I need to know is whether something is a
> type, a constant, a function, a macro &c.
>
> In all honestly, organising things by Types Functions Macros
> is like the bad old days of Pascal programs where you had to
> put all the labels, then all the constants, then all the
> types, then all the variables, then all the procedures and
> functions, meaning that you had to rip semantically related
> things apart on implementation grounds.
>
> I can only see one major difference: the function list for a module is
>> inline (elixir) instead of in the sidebar (erlang). Which one is best?
>> I've heard people arguing for both.
>>
>
> They are both wrong.  They are alphabetic rather than topical.
> This has, for example, the *ABSURD* consequence that
>     binary_to_term/1
>     term_to_binary/1
> are far from each other in the erlang module's documentation.
> Similarly, the weeping members of the integer_to_list/1,
> list_to_integer/1, float_to_list/1, list_to_float/1 family
> are cruelly separated.
>
> More precisely, they are both half right.   If I *know* which
> function I want, the alphabetic list helps me find it quickly.
> But if I only know what the function is *about*, the alphabetic
> list helps very little.
>
> The actual descriptions of semantically related functions should
> be physically close in the body of the text so that when I am
> looking at one, a related one is just a glance away.
>
>
>> IMHO, presenting reference documentation so that everybody is pleased is
>> extremely difficult, because people use the docs in many different ways.
>> Different layout and information detail are most useful for beginners
>> (that browse to see what's available and might learn something unrelated
>> in the process)
>> than for people that mostly know what they look for (that need fast
>> access to some detail, often from the shell).
>>
>
> If there's anyone here who is NOT a beginner, it's surely Joe
> Armstrong.  Yet he has made the point that in each module that
> he uses, there is a small number of functions that he uses a lot,
> and the rest which he uses very seldom.  That means that
> *sometimes* when he looks at dict *sometimes* he will be approaching
> it as an expert refreshing his memory about something and
> *sometimes* he will be approaching it as a beginning looking for
> information about a function he uses so rarely he can't even recall
> its name.
>
> Every release there seems to be new stuff in the erlang: module,
> so every release I am a beginner again about *something* useful
> in that module.
>
> It's also difficult to create a presentation that works for a full-blown
>> browser as well as for lynx.
>>
>
> It doesn't have to be the same HTML file does it?
> HTML-optimised-for-Lynx-or-w3m-or-Emacs-w3 and
> HTML-optimised-for-Firefox-on-a-huge-screen and
> HTML-optimised-for-a-Windows-phone
> really need to be three different versions.
>
> ≥ I'm not referring to the visuals, but the
>
>> module and function index, which is
>> huge and needs to be folded. I can't come up with a way to do that
>> without javascript.
>>
>
> But I don't *want* "huge" function and module indices
> in my pages all the time.  (Hint: "huge" lists are hard
> to find things in.)  There's one thing I do heartily
> approve of in the Elixir pages, which is that there is a
> very simple way to get rid of the navbar.  In fact I'm
> personally quite happy to have
>  - a module list in one tab
>  - a topic (NOT function!) list in another tab
>  - the main text scrolled to the current topic in another tab
> because quite often when I click on a navbar link what I
> want is to see another topic *as well* (in a new tab),
> not *instead* of the one I'm looking at.
>
> BTW, it's trivial (see comment above regarding html friendliness,
>> though) to make the erlang docs look more like elixir's while keeping
>> the good parts. See picture :-)
>> https://www.dropbox.com/s/jqpqpcimv3qxdce/e0.png?dl=0
>>
>
> Problem 1:  the structure is
>  <highly obtrusive bar> <function header>
>     Types:
>       <argument and result types>
>
>     <text>
>
>   [ Example:
>     <Haskell doctest-style example> ]
>
> The word "Types:" is pointless.  I can *see* that they are types.
>
> Problem 2:  if anything should be highlighted here, it is the
> function name.  If the function name is bold. there's no need
> for the <highly obtrusive bar>, and my eye is directed to the
> most salient piece of information.
>
> Problem 3:  the font used for code in the <function header>
> and <argument and result types> and the font used for code
> in the <text> are not the same font.  Worse still, the
> font used for the expression in the <Haskell doctest-style
> example> and the font used for the result are not the same
> font.  (Or more precisely, they may be different weights of
> the same font.)
>
> Problem 4:  the font used for code in the <text> does not have
> the same x-height as the font used for ordinary text.  The
> code font is markedly smaller.
>
> Problem 5:  the font used for code in the <text> and for the
> result in <...example> are markedly fainter than the other
> fonts.
>
> I could go on.
>
> But this is the fundamental problem with trying to do fancy
> typography in HTML.  It is very very hard to make it look good.
> If you want fancy typography that actually looks good,
> PDF is the only game in town.
>
> HTML is just the wrong tool for that job.
>
> HTML is great for when you have no idea what the user's
> screen resolution is, very little idea what fonts they
> have, how big their browser window is, whether they can
> discriminate colours (and in our fairly small department,
> two of my colleagues are red-green colour-blind, making
> many syntax colouring themes worse than useless for them),
> whether they can tolerate small text, ....
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160929/9af7e4ad/attachment.htm>