[erlang-questions] Erlang documentation -- a modest proposal
Richard A. O'Keefe
Tue Sep 27 04:38:48 CEST 2016
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.
More information about the erlang-questions