[erlang-questions] Accessing the documentation at runtime

[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?

*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!

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*.

-- 
Loïc Hoguin
http://ninenines.eu
Author of The Erlanger Playbook,
A book about software development using Erlang