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

[Lutz Behnke]

All your points are true. But unless the developer is also gifted with 
far above average discipline _and_ the ability to write good 
documentation, your approach does not result in good documentation.

As Joe pointed out, management does not place great value in 
documentation specialists, nor is it a developers skill in high regard 
in most organisations. In my personal experience, even university level 
education is aimed against it ("..auto-testing, style-checking, 
documentation, version control, what else? We are teaching programming! 
For the rest there is no time!"). Given those preconditions, I think the 
OTP team has done a stellar job.

Focus any resources of writers, editors, typesetters, etc. on providing 
good tutorials and user guides. Get new people riding the train before 
they have to dive into the reference material.

To the trained reader, the resulting code is at least as obvious as XML 
source. You will have a generate HTML and PDF for both methods. But most 
importantly, when the source changes, there is at least some chance, 
that the documentation will be fixed as well. Or at least marked as 
incorrect. Bad, but better than docs and behavior obviously 
contradicting themselves.

I have written docs in man/nroff, info, have submitted small patches to 
the RPM manual in docbook and usually write anything longer than a 
single page in LaTeX. But still find the mixing of code and 
documentation to generate the most helpfull information for the user in 
the absence of a team of technical writers (or source authors that are 
also able to write good documentation).


mfg lutz

Am 23.09.2016 um 11:17 schrieb 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,
>

-- 
Lutz Behnke
Hochschule für Angewandte Wissenschaften Hamburg,
Labor für Allgemeine Informatik,

phone: +49 40 42875-8156    mailto:lutz.behnke@REDACTED
fax  : +49 40 2803770       http://users.informatik.haw-hamburg.de/~sage
Berliner Tor 7, 20099 Hamburg, Germany