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

Lutz Behnke lutz.behnke@REDACTED
Tue Sep 27 14:19:24 CEST 2016


Am 26.09.2016 um 23:49 schrieb Richard A. O'Keefe:
>
>
> On 26/09/16 6:40 PM, Lutz Behnke wrote:
>>> (For maintenance purposes, I would like to track code
>>> changes separately from documentation changes, but that's
>>> another issue.)
>>
>> How do you keep track of source changes making it into doc changes?
>
> I don't understand the question.  If you are talking about a change
> to the source code that has a corresponding (but necessarily
> different) change to the documentation, then they form a single
> commit with a common MR or other identifier (if such are used).

Yes, if the documentation is done properly and the programmer also has 
the necessary skills as a writer.
I have worse eperience that led many project to the state you describe 
below.

>>
>> Possibly, my level of expectation is so low, that I find almost any
>> published doxygem better that having to pick apart the source drop.
>>
>> If the user doesn't know what he or she needs yet, then reference docs
>> (which I was specifically targetting) are not the right piece of the
>> docs for them.
>
> I was thinking of a number of fairly popular open source projects
> where there was a sketchy tutorial and then a Doxygen puke (with
> many of the functions uncommented, just automatic headers) *instead*
> of documentation.

That is _no_docs_ and should not count ;-) But Erlang currently is far 
beyond that state.

>
> Actually, if you look at source code, there are often cues to be had
> from the words inside the functions.

But it is not presented separately and with a minimal barrier of entry, 
have some amount of pretty pringint. Thus pure source code is the method 
of last choice for projects that fall into the _no_docs_ category.
>
> I guess it depends on what you mean by "published Doxygen".
> I was meaning "so-called documentation made available to people outside
> the project generated using Doxygen."
>
> BTW: I am painfully aware that my own documentation skills leave much
> to be desired.
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions


-- 
Lutz Behnke
Hochschule für Angewandte Wissenschaften Hamburg,
Labor für Allgemeine Informatik,

phone: +49 40 42875-8156    mailto:lutz.behnke@REDACTED
fax  : +49 40 2803770       http://users.informatik.haw-hamburg.de/~sage
Berliner Tor 7, 20099 Hamburg, Germany

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 5006 bytes
Desc: S/MIME Cryptographic Signature
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160927/b777fed4/attachment.bin>


More information about the erlang-questions mailing list