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

[Loïc Hoguin]

On 09/23/2016 10:36 AM, Lutz Behnke wrote:
> I would propose a position specific to the reference documentation:
>
> 8) Put the documentation in the source code. Use edoc (or similar new
> tool).

And I would strongly advise against that.

It may sound like a good idea from a programmer's perspective, but it 
would make the life of any writer, editor, typesetter and others 
difficult. Then there's the finer issues:

* Your documentation goes from everything in one place to small chunks 
interspersed here and there in the source files
* It is not obvious what content the documentation will have until you 
generate it
* Features like edoc's use of -spec declarations are not helpful; there 
is often a difference between what a function allows (the spec) and what 
is documented publicly (the doc)
* This tends to make the source code the authority rather than the 
documentation, yet people write code against documentation so extra care 
should be taken to make it usable without looking at the source. It's 
much harder to do this when it's just next to the source
* Etc.

Personally I consider projects that only have doc comments to have no 
documentation at all. If the documentation is in the source I might as 
well just open the source files, I'll be sure to have up to date 
information there since (doc) comments tend to lag behind.

Doc comments are the lazy programmer's solution. There's plenty of 
formats for writing documentation, I'd advise everyone to learn one or 
two. OTP uses docbook for better or worse. I personally use Asciidoc 
(which generates docbook and from there a variety of formats). There's 
various other formats each with their strengths and weaknesses, and most 
of them generate docbook at some point.

I know full well writing documentation is hard. But it's worth doing 
extra efforts to get a great result.

FYI I am currently working on improving the Cowboy function reference. 
My tentative currently looks similar to this for "man 
cowboy:start_clear": 
https://gist.github.com/essen/3affa1c8e7805a7dc867156b03c1854f - in 
HTML/PDF form it would of course have syntax highlighting, proper links 
and so on.

And this brings us back to one of my points: the *content* is what 
matters. And it's a lot harder to focus on that content when this 
content is scattered in a zillion source files.

Cheers,

-- 
Loïc Hoguin
http://ninenines.eu
Author of The Erlanger Playbook,
A book about software development using Erlang