[erlang-questions] Erlang documentation -- a modest proposal
Tue Sep 27 11:58:05 CEST 2016
On 27/09/2016 10:08, Kenneth Lundin wrote:
> Interesting would be to know how many % of the users that actually are
> using the man and pdf pages.
I mostly just lurk on this list, trying to pick up pearls from the
sidelines, but for what it's worth, I use the man pages heavily when
writing erlang. Maybe even saying I rely on them isn't too strong.
They're fantastic, and I'd be really sad if they went away. I definitely
use the online HTML manuals a lot when planning, designing and working
out how to do things, and take the PDFs with me when on a flight or long
journey - but when actually writing code, the man pages are invaluable.
They form a concise, specific and appropriately terse reference that's
right there when you need it, and the context-switch of having to swap
from terminals to browsers just to look up "what was the signature for
that function, again?" (a regular occurrence for me, especially with a
platform of erlang/OTP's sheer scale) is just yet more load that my old
brain could do without. I'm sure I could get used to using lynx with
some alias or other, but I'd rather not have to, and I'd much rather
have the man pages available on my disk, without relying on the network.
Honestly I wish more platforms had the kind of reference support that
erlang's man pages give it. I absolutely agree that the pithy-example
content that Joe and Loïc have suggested would be great, and maybe
different formatting/layouts alongside a re-org for some of the doc
structure would be helpful - but for me, not so much that either would
warrant taking away 'erl -man', if there's a choice to be made.
Anyway, as always, thanks for the amazing platform *and* its documentation,
More information about the erlang-questions