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

Wed Nov 21 21:02:34 CET 2018

Thanks for the thoughts and tips, Ivan!

Love your quote:

"The Unix environment is an ocean in which a gnat may drink and an elephant may bathe"

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

I work alone on many fronts so, beyond the wonderful people on this list, depend upon books and the web as I try to become sufficiently competent in the many tasks required to bring the ambitious web app I've been working on to fruition. Documentation is often a make or break for me when I evaluate an app or tool. If I don't understand it, which happens all too often, it's Sayonara for that app.

This is complicated by the fact that as I age I don't retain information as well as I once did. So I've been struggling to develop a format and system for keeping track of all the things I need to know. 

I hope soon to propose documentation for creating publish source GitHub repositories. If time and energy allow, I'll try to follow it up with a stab at a "Building Erlang on Ubuntu" draft inspired by Fred Hebert's suggestion.

I need to understand how to put such documents on the web, so I'll do so as time permits.

Thanks again,

Lloyd

-----Original Message-----
From: "Ivan Uemlianin" <ivan@REDACTED>
Sent: Wednesday, November 21, 2018 6:59am
To: erlang-questions@REDACTED
Subject: Re: [erlang-questions] Documentation -- what I ran into when I installed kerl

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 which a 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 ]( mailto: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 ]( mailto:erlang-questions@REDACTED )[ http://erlang.org/mailman/listinfo/erlang-questions ]( http://erlang.org/mailman/listinfo/erlang-questions )

-- ============================================================Ivan A. Uemlianin PhDLlaisdyYmchwil a Datblygu Technoleg LleferyddSpeech Technology Research and Development                    [ ivan@REDACTED ]( mailto:ivan@REDACTED )                        @llaisdy                         llaisdy.wordpress.com              github.com/llaisdy                     [ www.linkedin.com/in/ivanuemlianin ]( http://www.linkedin.com/in/ivanuemlianin )                        festina lente============================================================ 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20181121/5bc56d6a/attachment.htm>