[erlang-questions] Accessing the documentation at runtime

[Lutz Behnke]

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
>> <lutz.behnke@REDACTED> 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: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/20160929/d8bd93af/attachment.bin>