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