[erlang-questions] Erlang documentation -- a modest proposal

[Igor Clark]

Hello wizards,

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,
Igor