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

[lloyd@REDACTED]

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?
 
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.
 
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"
   
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
 
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.
 
Again,  it took a bit of time looking up package names to meet the requirements. Given that, the following console commands filled in the blanks:
 
~$ sudo apt-get install xsltproc
~$ sudo apt-get install libncurses-dev
~$ sudo apt-get install automake
~$ sudo apt-get install autoconf
~$ sudo apt-get install xsltproc
~$ sudo apt-get install fop
 
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.
 
All that said, thanks to the kerl authors for a very useful tool. My next step now is to build the Erlang docs.
 
Best wishes,
 
Lloyd
 
 
 
 
 
 
 
 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20181120/7dc6ec89/attachment.htm>