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

[Joe Armstrong]

On Fri, Sep 23, 2016 at 12:02 PM, Loïc Hoguin <essen@REDACTED> wrote:
> 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.


Yes - writing is a learnable skill. I was crap at writing English in school.
My spelling was terrible, punctuation non-existent.

It took me 4 books to get to the point where I could say that I was good
at writing.

Nothing comes for free - the code I write, I write, then throw away
then rewrite and throw away until it is beautiful.

Same with English  - write throw away - rewrite. Write more than you need
and throw away the worse paragraphs - this emphasises what is left.
After ten year you get good at it.



> 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.

If the programmers need to read the code to understand what your
program does, then you have failed to write good 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.

Yes ^ 1000

The code (if you can understand it) tells the machine what to do.

The documentation tells the reader what the program is *supposed* to do.

Since the two are not usually the same it's a good idea to have some
documentation that tells the poor sod who wants to use your code what
it's supposed to do.

/Joe

>
> --
> Loïc Hoguin
> http://ninenines.eu
> Author of The Erlanger Playbook,
> A book about software development using Erlang
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions