[erlang-questions] Documentation -- what I ran into when I installed kerl
Wed Nov 21 02:24:05 CET 2018
On 11/20, lloyd@REDACTED wrote:
>We all know that writing software documentation is hard. I tip my hat
>to all who strive to do it well.
>My sense is that software docs are living documents ideally drafted
>through an iterative process that involves several cycles of unwitting
>users attempting to follow the how-to-install/how-to-use recipes
>proposed in the documentation followed closely on by doc revision based
>on user experience.
>This does lead to a challenge: how much can the doc writer reasonably
>assume about user knowledge and experience?
I tend to write a decent amount of documentation, and what you state
right here is a major hurdle. It's really hard to figure out your target
audience, and communicate that clearly. It's equally hard to remember
what your system was like before you had installed all the right
dependencies, and it's really easy for things to slip from your mind.
The thing I rely on to help in such cases is reader questions to
highlight the problems I had and the things I forgot.
I didn't write the kerl documentation, so that being said, I don't
necessarily know who it is targeted to. I know I can read it fine, but
I'm no longer a beginner either.
>Assume too much and you frustrate naive but motivated users. Assume to
>little and you risk frustrating knowledgeable users. I really don't
>know the best compromise. But it is a concern I believe worthy of
>discussion and debate.
Yes. I think what we are missing as a community is a well-defined "how
to install Erlang on your system" style of documentation that is
well-visible and maintained. That way, tool developers could point to
that document as a foundational step, and people whose setup is complete
can easily skip it.
>For what it's worth, here's what I ran into when I installed kerl:
>1. First roadblock -- my lack of a lowl-level Linux skill, e.g. adding
>kerl to PATH. Dan Sommers provided the simple solution:
>$ cp $HOME/kerl $HOME/bin/
>Dan's solution worked a charm. Perhap it can be added as an example
>under the current instruction in kerl docs:
>"and drop it in your $PATH"
This only works because Dan noticed that `$HOME/bin/` was already in
your path. But yes, the `$PATH` environment variable is something the
tool author assumed the reader was familiar with.
It's an environment variable that contains directories where common
executables can be found. Your shell of choice (bash, sh, csh, zsh,
etc.) all have a dotfile (.bashrc, .zshrc) where you can do things like
which essentially adds $HOME/some/path to the head of all the paths your
shell will look into for executables.
>2. When I executed $ kerl build 21.1 I again ran into failure-- needed
>ncurses library. Took 15 minutes to find the right package name, but
>the solution was:
>~$ sudo apt-get install libncurses-dev
Right. This, at this point, was a missing dependency of Erlang/OTP
itself. libncurses is a library used to handle fancy terminal output
sequences like those you see when progress bar animations are drawn in
Libncurses-dev is a package containing the source files to that library
so that your own executables can be built against them and also contain
When compiling software, you will often need to download additional
*-dev packages for this reason.
>3. Retried $ kerl build 21.1 and it worked but with numerous moans and
>Building Erlang/OTP 21.1 (21.1), please wait...
>WARNING: It appears that a required development package 'automake' is
>WARNING: It appears that a required development package 'autoconf' is
>APPLICATIONS DISABLED (See:
> * jinterface : No Java compiler found
> * odbc : ODBC library - link check failed
>APPLICATIONS INFORMATION (See:
> * wx : wxWidgets not found, wx will NOT be usable
>DOCUMENTATION INFORMATION (See:
> * documentation :
> * xsltproc is missing.
> * fop is missing.
> * xmllint is missing.
> * The documentation can not be built.
Automake and autoconf are useful to have in general, and it's the kind
of thing that trips me up every time I set up a system for the first
time, but after that you never need to reinstall it again. It is
something I always forget in instructions because unless I do it on a
new machine or virtual machine, it never errors out.
The other errors are optional dependencies for optional libraries
(jinterface lets your erlang talk to java, odbc is a generic database
driver for SQL databases, wx is the graphical toolkit that can be used
by libraries like observer) and dependencies (xsltproc allows XML
processing when building the doc, fop has something to do with PDF
generation of the doc, and xmllint is likely XML validation for the
Your system should be usable, but if you see a tutorial break when you
call `observer:start()`, it will be because of that missing wx
>Some of these package names may be Ubuntu specific, which certainly
>makes doc drafting more difficult. But it would have saved considerable
>time and a bit easier on the blood pressure if kerl docs provided
>forewarning and, even better, a working example.
Exactly; these _are_ ubuntu-specific, and each linux distribution may
cut up their packages differently. So documentation writers will tend to
just tell you to get a copy from a package manager, which leaves you on
your own for kerl.
It lets us off the hook for the installation of the system and we
handwave all responsibility away.
I personally run Windows 10, OSX, a LTS copy of Ubuntu, and a FreeBSD
distro on a raspberry pi, and I still avoid some build instructions
because you never really know how things end up when distribution
maintainers change how things are cut up.
More information about the erlang-questions