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

[Loïc Hoguin]

I'll agree to disagree. I'll comment on one point though:

On 09/23/2016 11:43 AM, Lutz Behnke wrote:
> 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.

This is no gift, this is learnable skills and I would argue the first 
step to discipline yourself is to separate code and documentation; and 
the second step is to write or update the documentation before any code 
is written.

As far as users are concerned, your documentation is your program, not 
the code. The code is for the developers of the program and the 
machines. Therefore what you really need to get right for your users is 
the documentation.

It's different for internal libraries that have no direct users except 
the development team, and those are a lot more common than public 
libraries, which is probably why documentation is held in such a low 
regard. And perhaps doc comments are more than enough for that kind of 
project.

But for libraries used by thousands of people or more? You definitely 
should spare no effort. Learn how to write great documentation. Iterate 
until you get something great. Even small improvements will end up 
having a huge impact over all users.

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