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

[Fred Hebert]

On 11/20, lloyd@REDACTED wrote:
>
>Hello,
>
>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?
>

Hi Lloyd,

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

export PATH="$HOME/some/path:$PATH"

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 
the terminal.

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 
that functionality.

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 
>growns:
>
>Building Erlang/OTP 21.1 (21.1), please wait...
>WARNING: It appears that a required development package 'automake' is 
>not installed.
>WARNING: It appears that a required development package 'autoconf' is 
>not installed.
>APPLICATIONS DISABLED (See: 
>/home/lloyd/.kerl/builds/21.1/otp_build_21.1.log)
> * jinterface : No Java compiler found
> * odbc : ODBC library - link check failed
>APPLICATIONS INFORMATION (See: 
>/home/lloyd/.kerl/builds/21.1/otp_build_21.1.log)
> * wx : wxWidgets not found, wx will NOT be usable
>DOCUMENTATION INFORMATION (See: 
>/home/lloyd/.kerl/builds/21.1/otp_build_21.1.log)
> * 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 
docs).

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 
dependency.

>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.

Regards,
Fred.