[erlang-questions] Accessing the documentation at runtime

[Loïc Hoguin]

On 09/29/2016 02:00 PM, Lutz Behnke wrote:
>> *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.

But that's already the case. I only have man pages; I don't have HTML or 
PDF.

> 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

You are kidding?

Now Erlang needs to come with converters for every format people use. 
I'm advocating using a third party tool that handles all this mess 
automatically and produce the files along the release; up to you whether 
to install them or not.

My development system only has man pages; my CI servers don't have any 
documentation, as it should be.

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

Didn't say it couldn't be useful to integrate into IDEs. It's the rest 
that I have problems with. We don't need more custom code for building 
the documentation; we need less.

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