[erlang-questions] Erlang documentation -- a modest proposal
Fri Sep 23 12:59:02 CEST 2016
On Fri, Sep 23, 2016 at 12:02 PM, Loïc Hoguin <> 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
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
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.
> Loïc Hoguin
> Author of The Erlanger Playbook,
> A book about software development using Erlang
> erlang-questions mailing list
More information about the erlang-questions