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

[Richard A. O'Keefe]

On 27/09/16 7:01 AM, Marco Molteni wrote:
> my suggestion for the documentation format is asciidoc.

I think the kind of "format" that people were concerned about
is *presentation* format.

 From the point of view of someone *reading* documentation,
it's really not very interesting how the documentation was
*written*.  The issues that matter most are
  - is the text clear and good enough that its errors
    in spelling/grammar/punctuation aren't distracting?
  - is the information correct?
  - is the information adequate?
  - are there appropriate navigation aids to help me find
    related content easily and obviously?
  - is the content up to date?
After that we care about
  - is all the information accessible through audio?
  - have contrast-reducing things like coloured text
    been avoided in everything the user needs to read?
  - does the typography direct the reader to important
    things or is it distracting?
  - does the presentation form need a manual or is it
    obvious to anyone familiar with (reading paper /
    using a PDF viewer / using a web browser)?
  - can the documentation be plugged into an IDE
    (including the UNIX command line as an IDE)?

As someone who would like to offer the occasional
correction/extension to the Erlang documentation,
then I care about the markup language.

As for asciidoc, let's just say that when I installed it,
I had to fight my way past dead links, install Yet Another
Fine Build program, install yet another program, fight my
way past dead links in that, and then when I was finally
able to run 'a2x' on something, it claimed that xmllint
didn't like the output except that xmllint *did* like the
output, and at that point I gave up.  But not before I had
tried installing asciidoctor, which didn't work (dead gem
link, I think).  And all of that was today.

(I am also heartily sick of programs that assume that if
you are using a Mac you have full root access and can use
things like Fink and Brew and install things in places
other than your own ~ tree.  It just isn't so.)

I have *roff (both Legacy and GNU), (La)TeX, Lout,
an assortment of tools for processing SGML and XML,
FOP, Erlang, &c.  I also have multiple Markdown tools
(because there are so many Markdowns) which I only use
to process other people's stuff.  I am so tired of NIH.
So very very tired of it.

> And it is the only format I ever found that allowed me to avoid LaTeX

I for one have no particular desire to avoid LaTeX.
It doesn't constrict the range of the thinkable the way
that Markdown does.