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

[Ivan Uemlianin]

Dear Lloyd

Kerl is fantastic and I use it a lot, but I have struggled with the 
documentation like you have (in my case getting it to work on a Mac).

Kerl's documentation is very far from the worst for an open-source 
project.  The only real way to test installation and "getting started" 
docs is to have someone not involved in the project to install and run 
the software --- preferably under observation and at a time and place 
not of their choosing.

I now have kerl running happily on a Mac and on Ubuntu.  (Feel free to 
ping me offline if I can help.)

The Unix environment is an ocean in whicha gnat may drink and an 
elephant may bathe, which does complicate things.  In case you haven't 
come across it already, I find alias very handy, e.g., I have these 
lines in my .alias file (or you might have .bash_aliases on Ubuntu):

     alias erl18='.  ~/bin/erl_kerl_builds/r183/activate'
     alias erl20='.  ~/bin/erl_kerl_builds/r203/activate'
     alias erl21='.  ~/bin/erl_kerl_builds/r210/activate'

(That '.' is a synonym for the command 'source'.)

So instead of having to type out '. ~/bin/erl_kerl_builds/r210/activate' 
I can just use erl21.

Happy hacking!

Ivan


On 20/11/2018 22:37, 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?
>
> 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
>
>
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions

-- 
============================================================
Ivan A. Uemlianin PhD
Llaisdy

Ymchwil a Datblygu Technoleg Lleferydd
Speech Technology Research and Development

                     ivan@REDACTED
                         @llaisdy
                          llaisdy.wordpress.com
               github.com/llaisdy
                      www.linkedin.com/in/ivanuemlianin

                         festina lente
============================================================

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20181121/cdd8eb9c/attachment.htm>