[erlang-questions] Documentation -- what I ran into when I installed kerl

empro2@REDACTED empro2@REDACTED
Thu Nov 22 15:10:31 CET 2018


On Wed, 21 Nov 2018 15:02:34 -0500 (EST)
lloyd@REDACTED wrote:

> And I would add, "and where a noobie can all too easily
> flounder around lost at sea."

The one big asset newbies bring is: they do not know what
is meant.

Those who know how it works often write for those who
already know anyway (and only need something to remind
them), but their asset is: they know how it works.

By the time people have kept track of enough of the things
they need to know to write their own, additional, "how to",
they have lost (too?) much of their original asset by
gaining some of the other.

Having been suggested to use git (pull requests) to
contribute to the Erlang documentation has made me
wonder what the best (or a good) way to combine these
two assets could be. Well, I wanted, or needed, or wanted to
because I needed to learn git anyway, but is that an
efficient way to rephrase some distractingly strange phrase
in the docs? or to correct some typo?

And I will not start to write up my own documentation on
mod_esi, httpd, inets, applications and application
controllers, mnesia, match specs, Emacs lisp, git, github,
JIRA Agile and all the other things I need to know (and
those I am too curious to skip - and that does not kill the
cat only ... ;-). That is too much work for a single person,
even more so as it is bound to be partially redundant, and:
were it not so inefficient, I would hang myself every time
I get confused by a piece of my own documentation ;-)

Might not be a silver bullet, but as documentation needs to
be quickly accessible (for the authors especially!) a wiki
might serve well. But it is not that simple and I intend to
start some separate thread about more efficient
contribution. Hope I keep that intention beyond getting
some practice with git, avoiding a github account and a
JIRA (or Agile?) account, but I am not yet sure that I know
what I am doing and I want to avoid bothering people on
this list too much.

But I might be already by straying too far from the
topic ...

Taking from the tone of some previous e-mails in this
thread it might not hurt to point out that criticism can be
a way of appreciating the loads of good and hard work that
went into Erlang, kerl, git, ..., and their documentation
too. Criticising can take a lot of time and who would want
to waste time on rubbish :-)

Intimidated by kerl's power I realised that I did not
really need to serve different versions of Erlang/OTP nor to
keep up to date (yet?) and was fine with something like
    $ sudo apt-get install erlang

I know kerl is there should I need it, and I hope it will
then be easy to contribute to its documentation :-)

Michael

-- 

“Even after a thousand explanations a fool is no wiser,
whereas someone intelligent requires only one fourth of
these.”

	– from the Mahābhārata (महाभारत)






More information about the erlang-questions mailing list