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