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

[lloyd@REDACTED]

Much applause.

Some coordination with Erlang Central might generate valuable synergy.

There hasn't been much mention of tutorials. I agree that they shouldn't be in reference docs. But from my perspective as one striving to learn from books and the net, they are invaluable. Ideally they are simple projects that result in a useful tool or application.

LRP

-----Original Message-----
From: "Kenneth Lundin" <kenneth@REDACTED>
Sent: Tuesday, September 27, 2016 3:44am
To: "Lukas Larsson" <lukas@REDACTED>
Cc: "Lloyd R. Prentice" <lloyd@REDACTED>, "erlang-questions@REDACTED" <erlang-questions@REDACTED>
Subject: Re: [erlang-questions] Erlang documentation -- a modest proposal

Hi,

I have followed this thread with interest since there are many good
suggestions and ideas. As Lukas mentioned it would be good if we could
agree on some action(s) in which the community could contribute.

First some info about what we (The OTP team at Ericsson and the Industrial
Erlang User Group) plan to do.

- Nicer , better HTML layout of the docs. The Elixir look layout looks
quite nice and since it is overlapping communities it could be good to have
the same or similar layout. The HTML, CSS, Javascript setup  seems quite
well thought.
Take a look at http://elixir-lang.org/docs/stable/elixir/Kernel.html#
full-list.
If you have suggestions regarding the html layout they are welcome. In that
case it would be nice with a small example showing for example the
beginning of the lists module and a few functions. Note this step does not
require changes of the doc source which is XML it is just a matter of
tooling. Translating the current XML to html (when you know what html you
want).

- Making it easier to contribute with documentation improvements. One
simple step can be to add a link to the doc source at github from the
generated html page. Another to write a short guide on how to contribute to
the documentation.

- Having technical writers going through the documentation in order to
correct language and consistency. This is ongoing.

- Making the search in documentation on www.erlang.org more visible. You
can search on application, modules, functions.

- Validate the current doc sources with XMLLINT to assure that we are
following our own DTDs. This is almost done and with this in place it is
easy to translate the doc sources to some other format like a simpler XML
dtd (or XSD), asciidoc or even markdown. Note that there is only one common
source for the documentation and it is in XML with a few exceptions. Each
application has a doc/src directory where its documentation source files
are. There is module references for the modules with public APIs and a User
Guide (mostly).

From this thread I think the following are the most interesting
suggestions:

Examples in the doc
------------------------------

I agree that we need more examples in the documentation. It would for
example be good to have a short example for
almost every function in a module.

This can be done in various ways. Either embed the example in the text or
have a separate example file in parallell with the text. In both cases I
would like to have the possibility to automatically check the syntax and
execution of the example during the build documentation build process. If
not checked we will soon have a number of non working examples.

The presentation view of examples is just a tooling question independent on
the actual source for the examples. The first thing is to create the source
for examples and what format we should use for this (same for all modules
of course).

Man pages or not?
-------------------------

I understand that some of you are using the man pages. But the question is
why are you using them?
Is it because it is easy to type "man lists" or "erl -man lists"? What if
"erl -man lists" pops up in a web-browser window of you choice instead?,
Note that it is exactly the same information shown in the lists.html and in
the man page for lists.

PDF or not?
------------------

I think it is rather unusual that the PDF pages we generate to day are used
compared to the HTML variant. Correct me if I am wrong.
Perhaps Epub or something else would be more useful. I suppose the html
variant could also support printing and or saving as pdf without to much
effort from our side.

More User Guide oriented text or cook books.
---------------------------------------------------------------

This is very valuable but does not have to be part of the Erlang/OTP
release. Could be hosted on a web-site like Erlang Central (and there is
already material like this there I think).

I have probably forgotten lots of things that I should have mentioned and
commented , but this is it for now.

/Kenneth, Erlang/OTP , Ericsson