Learning from the Manual

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Learning from the Manual

Peter J Etheridge
Dear List,
I assume the Manual is clear to those who understand it.
For noobies [like me], the Manual can be re-read and still not explain 'why' or 'how', or answer a question.
Clearly, the Manual needs to be read in conjunction with ROK's email responses.
Noobies only learn from Dan & ROK's informative answers when someone as game as Lloyd asks questions.
I try to imagine Joe's idea of URL's or UUID's somehow linking the Manual to Roger's stash of ROK's answers.
Might the Manual be improved by some FAQ in each module?

_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Learning from the Manual

Matthias Lang
On 20. September 2016, Peter J Etheridge wrote:

> Dear List,I assume the Manual is clear to those who understand it.
> For noobies [like me], the Manual can be re-read and still not explain
> 'why' or 'how', or answer a question.Clearly, the Manual needs to be
> read in conjunction with ROK's email responses.

If you're a "noobie", you _can_ learn Erlang from the reference
manual. But it's hard work. Much easier to work through an
entertaining and carefully thought out tutorial, i.e.:

   http://learnyousomeerlang.com/content

I took a look at his "datatype" section to see how he dealt with the
"there aren't actually any strings" problem. And it turns out there is
no string section!  Perfect.  Instead, the "Lists!" section shows
strings as one possible use of lists, which makes it a natural place
to present all the pitfalls. I'm looking at:

   http://learnyousomeerlang.com/starting-out-for-real

As someone who's written both manuals and FAQs, I think
learn-you-some-erlang has an unbeatable effort/benefit ratio,
especially for "noobies".

Matt
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Learning from the Manual

Miles Fidelman
And, I've found "Erlang and OTP in Action" to be very helpful in getting
from the basics to the design of real systems.


On 9/20/16 6:18 AM, Matthias Lang wrote:

> On 20. September 2016, Peter J Etheridge wrote:
>
>> Dear List,I assume the Manual is clear to those who understand it.
>> For noobies [like me], the Manual can be re-read and still not explain
>> 'why' or 'how', or answer a question.Clearly, the Manual needs to be
>> read in conjunction with ROK's email responses.
> If you're a "noobie", you _can_ learn Erlang from the reference
> manual. But it's hard work. Much easier to work through an
> entertaining and carefully thought out tutorial, i.e.:
>
>     http://learnyousomeerlang.com/content
>
> I took a look at his "datatype" section to see how he dealt with the
> "there aren't actually any strings" problem. And it turns out there is
> no string section!  Perfect.  Instead, the "Lists!" section shows
> strings as one possible use of lists, which makes it a natural place
> to present all the pitfalls. I'm looking at:
>
>     http://learnyousomeerlang.com/starting-out-for-real
>
> As someone who's written both manuals and FAQs, I think
> learn-you-some-erlang has an unbeatable effort/benefit ratio,
> especially for "noobies".
>
> Matt
> _______________________________________________
> erlang-questions mailing list
> [hidden email]
> http://erlang.org/mailman/listinfo/erlang-questions

--
In theory, there is no difference between theory and practice.
In practice, there is.  .... Yogi Berra

_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Learning from the Manual

Wilmar Pérez
In reply to this post by Peter J Etheridge
Hi Peter

I am in the same boat as you: very excited to learn Erlang but somehow finding clear information very cumbersome to get my hands on. Tutorials and many books (well, there are not that many), tend to stick to the basics or go right ahead to the overly complicated almost impossible to understand code. So far the most useful books I have found are "Programming Erlang" by Joe Armstrong and "Introducing Erlang" by  Simon St. Laurent.

If you find anything useful please send it my way. In an ideal world I would like to have something very similar to a university level course book with labs. 

Good luck with your learning

Regards,

Wilmar

2016-09-20 2:34 GMT-04:00 Peter J Etheridge <[hidden email]>:
Dear List,
I assume the Manual is clear to those who understand it.
For noobies [like me], the Manual can be re-read and still not explain 'why' or 'how', or answer a question.
Clearly, the Manual needs to be read in conjunction with ROK's email responses.
Noobies only learn from Dan & ROK's informative answers when someone as game as Lloyd asks questions.
I try to imagine Joe's idea of URL's or UUID's somehow linking the Manual to Roger's stash of ROK's answers.
Might the Manual be improved by some FAQ in each module?

_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions



_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Learning from the Manual

Richard A. O'Keefe-2
In reply to this post by Peter J Etheridge


On 20/09/16 6:34 PM, Peter J Etheridge wrote:
> Dear List,
> I assume the Manual is clear to those who understand it.

I've been reading programming language manuals since oh, 1974.
The first thing to say is that there are traditionally three
quite separate books:

  - Language Reference Manual
    (Overview, lexical structure, syntax, pragmatics, core library).
    For a rather bloated example of this, see the Java definition.
  - User's Guide
    How to use the compiler, linker, debugger; how to interface
    to data bases, other languages, networks.
  - Books for beginners, generally written by 3rd parties.

and there will also be

  - Documentation for major libraries.

And by the way, it really really helps if these things are available
on paper or in PDF form so that you don't have to go clickety clickety
OH MY CARPAL TUNNEL to get from one paragraph to the next.  Especially
with PDF or single-page HTML it is really nice to search for things
that the authors didn't think to index or link.

I did not say ONLY available in such forms.  If you look at the
Learn You Some Erlang for Great Good! web site you'll notice additional
material (like the stuff about maps and time measurement) in the on-line
version.  LYSE not being the Nugganite scriptures (from Pratchett's
"Monstrous Regiment"), new material doesn't magically turn up in paper
copies.

Any rate, the *point* is that from that long experience of reading
language reference manuals, I expect that *I* will be able to learn
a language from its reference manual, but that most others will find
it hard.  *Learning* Erlang is best done from the Erlang books listed
on the documentation page.

The rôle of the reference manual is to let you look up the details.
This is why it is so important to have it as a single file you can
search.  And it is important that all the details should be there.
(For example, I am not happy that the Erlang Reference Manual does
not include a formal grammar.)

In the case of programming languages, ANSI used to have a practice
of supplying separate "Standard" (WHAT) and "Rationale" (WHY)
material.  The C89 rationale is still worth reading.  ISO defenestrated
that.

All in all, I don't think the documentation is in *terrible* shape.
I've seen worse.

Hmm.  I have to get the next draft of a paper ready.  I was supposed
to get it done last week (sigh).  When I've done that, I might try my
hand at writing a chapter of an Erlang Reference Manual (NRSV) and
put it up for comments.

_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Learning from the Manual

Richard A. O'Keefe-2
In reply to this post by Matthias Lang


On 20/09/16 10:18 PM, Matthias Lang wrote:
>    http://learnyousomeerlang.com/content
>
> I took a look at his "datatype" section to see how he dealt with the
> "there aren't actually any strings" problem. And it turns out there is
> no string section!  Perfect.

The *paper* version has "strings" in the index, with
  - as binaries
  - a lists
  - to a number
as subtopics.

There's a great Open Source information retrieval engine
that can be used to power documentation searches.
It's called ATIRE, it has virtues too numerous to list here,
and it's free at http://atire.org/index.php?title=Main_Page
(The documentation could be better.  You get what you pay for.)

_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Learning from the Manual

Fred Hebert-2
On 09/21, Richard A. O'Keefe wrote:

>On 20/09/16 10:18 PM, Matthias Lang wrote:
>>   http://learnyousomeerlang.com/content
>>
>>I took a look at his "datatype" section to see how he dealt with the
>>"there aren't actually any strings" problem. And it turns out there is
>>no string section!  Perfect.
>
>The *paper* version has "strings" in the index, with
> - as binaries
> - a lists
> - to a number
>as subtopics.
>

Someone used the index! It's not anything special, but I'm glad to see
there was something useful in there -- I tried my hand at the craft of
indexing for the first time in the print copy of LYSE and dear lord
there's a lot of stuff in there nobody suspects exists. The Chicago
manual of style's pages on it were a revelation in terms of the
unexpected complexity of things I usually just skip over.

In any case, Matthias Lang does have a point where even though I mention
strings, it is mostly done in passing. There's a mention of regular
expressions (318, 325, 329-330), but topics having to do with the string
module, the binary module (which I'm not even sure existed back then?)
and topics having to do with Unicode are not discussed at all.

Someone looking for common functionality such as title-casing text
cannot find that information in LYSE (nor find out it isn't supported
anywhere else than in community libraries [1]).

LYSE was started around OTP-R13B. As we're nearing OTP-20, and within a
very different community landscape than back then, there's more and more
stuff that I feel is either missing, or no longer as important to show
in the book as it was back then.

I'd love to have time to work on a re-edition where stuff like releases
could be made 50 pages shorter by using tools like relx, add material
about the zen of erlang[2] and supervisor restarts[3], introduce maps
within the normal text flow, get people more hands-on time with dialyzer
and possibly property-based testing, make the FSM examples simpler,
possibly using gen_statem instead of gen_fsm, and possibly replace stuff
people use little of like distributed OTP releases and Mnesia to replace
them with a crash course in using tools and libraries from rebar3 and
the overall Erlang ecosystem for more common day-to-day tasks.  That's
without mentioning stuff like explaining how to get a proper SSL/TLS
configuration going (the defaults are *not* safe), time handling (which
could very well remain an annex), and so on.

The website's also due for a facelift, fresher documentation links, and
so on. I'd be interested to see what could be done with a more
interactive version, where the website asks to contact a local Erlang
server you run on your machine and lets you try snippets in JS (and
therefore circumventing the need to sanitize Erlang on a server, which
has proven hard and sometimes limitting before[4][5]).

So far there's not enough time. Plenty busy at work, open source
projects currently in flight (particularly rebar3) are fairly time
consuming, and No Starch hasn't been showing much initiative in pushing
for a new edition, but even then I'd probably want to get started on my
own so I can easily control the rights to a free online version.

There's also a bit of paralysis since I believe on of the reasons why
LYSE went so well the first time around is that I was writing it as I
was learning, and modifying it now would have me remove that perspective
from it. The expert's eye is quite different from the newcomer's and
manuals like Erlang in Anger[6] give a totally different experience. I'd
like to maintain the current perspective in LYSE as much as possible,
which could make it hard to accomplish some tasks such as say, move
Dialyzer content earlier, or think of a new chapter flow that moves the
user much closer to the action (although I can imagine using rebar3 and
its shell to get the readers in a better place to explore on their own
much earlier).

[1]: https://github.com/erlang-unicode
[2]: http://ferd.ca/the-zen-of-erlang.html
[3]: http://ferd.ca/it-s-about-the-guarantees.html
[4]: http://www.tryerlang.org/
[5]: http://erlangonxen.org/zerg is interesting though, but not quite
sure how good isolation would be there
[6]: https://www.erlang-in-anger.com
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions