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

[Richard A. O'Keefe]

On 23/09/16 3:18 PM, Kenneth Lakin wrote:
> On 09/22/2016 05:55 PM, Loïc Hoguin wrote:
>> Examples are never a bad thing to have; at worst they provide no value
>> for the majority of people;
>
> If they make the documentation hard to read and understand, they're
> definitely a net negative.

I can only say that I have found the occasional example in the Unix
manual pages to be a lifesaver, and that the presence of examples in
the R documentation has often made it straightforward to use something
whose description was not particularly helpful.  I suppose I can also
say that "show me a list of places where this method is called" has
been extremely informative when working on Smalltalk, even though those
aren't *crafted* examples.

Examples *instead* of documentation would be a bad thing.
Examples *mixed in with* documentation can be distracting.

So you have a library module.
There are
  - source code
  - documentation
  - examples
Thanks to the magic of hypertext, these things don't have to be in the
same view.  One reason for separating them is that somethings an
example *has* to be an example of several things, so it's nice that it
can be pointed to from several places, rather than duplicated.