[erlang-questions] Accessing the documentation at runtime
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.
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...
Size: 5006 bytes
Desc: S/MIME Cryptographic Signature
More information about the erlang-questions