[erlang-questions] Accessing the documentation at runtime

Lutz Behnke <>
Thu Sep 29 14:00:58 CEST 2016

Am 29.09.2016 um 13:14 schrieb Loïc Hoguin:
> On 09/29/2016 12:22 PM, Joe Armstrong wrote:
>> On Thu, Sep 29, 2016 at 9:43 AM, Lutz Behnke
>> <> wrote:
>>> Hi all,
>>> the discussion leaves me with the impression that everybody has his
>>> or her
>>> own method of accessing the documentation. And even that may change
>>> according to circumstances. I think a solution should be modular to
>>> cater to
>>> a wide range of personal preferences and situational restrictions.
>>> Joe's suggestion of a REST engine, that can provide the documentation
>>> in the
>>> format of your choice, does not automatically mean it only works online.
>> Not really - whatever you do on-line can easily be achieved with
>> a local webserver which can be packaged with the rest of the system
>>> Lets write a small doc-engine that can do all that. It should run as
>>> a self
>>> contained program on your local machine.
>> Yes - but it could use the same REST interface as above
> What kind of madness is this?

Different people consume documentation differently.
> *You should not have to run a server to read documentation!*
> Why would you open a socket to a local server (what port number btw?) to
> read a file that's *already on your filesystem*? Just open the file!

Because having each file for each format on disk is a waste. If you only 
ever want to use a single format, just prepare them for you. But don't 
force me to use a format, just because you like it.

I don't where you see the difference between a server/filter that can do 
it on the fly and some thin front-end that will prepare a complete doc 
bundle in a desired format

> I'd understand if you'd use Vlad's suggestion of adding support for an
> existing doc server for integration into IDEs; but a custom server on
> top of a custom documentation format makes absolutely no sense.
> You are not going to solve documentation problems by writing more
> programs. You solve documentation problems by writing more or improving
> what's already there; and in the case of OTP by reducing the amount of
> custom code needed to maintain it.
> Documentation is hard enough. Keep it *simple*.
Yes, but there are different people can solve different issues, due to 
different skill sets.

Reading/groking documentation is hard too, so it makes no sense to take 
people out of their comfort zone when using it. For me that zone is a 
combination of firefox, ctrl-f and google. You like man, IIRC Joe likes 
PDFs, Vlad wants integration into his IDE. Each to his own.

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

phone: +49 40 42875-8156    mailto:
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/20160929/d8bd93af/attachment.bin>

More information about the erlang-questions mailing list