[erlang-questions] Accessing the documentation at runtime
Thu Sep 29 13:14:13 CEST 2016
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?
*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*.
Author of The Erlanger Playbook,
A book about software development using Erlang
More information about the erlang-questions