Apology

classic Classic list List threaded Threaded
173 messages Options
1234 ... 9
Reply | Threaded
Open this post in threaded view
|

Apology

Richard A. O'Keefe-2
I have been taken to task in private e-mail by someone
who detected in my response to the "list comprehension puzzle"
both "aggressive sarcasm" and "undisguised contempt".

In all honesty, no sarcasm was intended. (A sarcastic response
would not have pointed to the Erlang reference manual.) Nor
was any contempt whatsoever involved.  I should not have to
reassure long-term readers of this mailing list that these
attitudes my critic claimed to detect were entirely imaginary.

However, it shows that it was possible for people to misread
what I wrote.  If anyone took offence at the message I
*meant* to be helpful, please accept my assurance that no
offence was intended and my unreserved apology for the offence.



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

Re: Apology

Loïc Hoguin-3
There was obviously no ill intent in that message. But intent is hard to
convey through text and people read posts with their own bias, which
leads to such imaginary interpretations. Nowadays an increasingly large
amount of people is looking to get offended; that's their own bias, and
anything ambiguous will be taken as offense. It's a shame as it makes
civil discussion and good intents much more difficult to pull off;
discouraging.

Anyway I'm probably not the only one who thinks you're doing a fantastic
job answering the many questions that are posted on this list, in great
details, regardless of how trivial they are or how confused the poster is.

Instead of you apologising, it should instead be everyone else thanking
you for this. So let me start. Thanks!

On 09/19/2016 07:05 AM, [hidden email] wrote:

> I have been taken to task in private e-mail by someone
> who detected in my response to the "list comprehension puzzle"
> both "aggressive sarcasm" and "undisguised contempt".
>
> In all honesty, no sarcasm was intended. (A sarcastic response
> would not have pointed to the Erlang reference manual.) Nor
> was any contempt whatsoever involved.  I should not have to
> reassure long-term readers of this mailing list that these
> attitudes my critic claimed to detect were entirely imaginary.
>
> However, it shows that it was possible for people to misread
> what I wrote.  If anyone took offence at the message I
> *meant* to be helpful, please accept my assurance that no
> offence was intended and my unreserved apology for the offence.
>
>
>
> _______________________________________________
> erlang-questions mailing list
> [hidden email]
> http://erlang.org/mailman/listinfo/erlang-questions
>

--
Loïc Hoguin
http://ninenines.eu
Author of The Erlanger Playbook,
A book about software development using Erlang
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Apology

Michael Nisi
I couldn't agree more. Your posts are an invaluable resource of knowledge and delight, which I always gratefully receive. Thank you!

On Mon, Sep 19, 2016 at 9:07 AM, Loïc Hoguin <[hidden email]> wrote:
There was obviously no ill intent in that message. But intent is hard to convey through text and people read posts with their own bias, which leads to such imaginary interpretations. Nowadays an increasingly large amount of people is looking to get offended; that's their own bias, and anything ambiguous will be taken as offense. It's a shame as it makes civil discussion and good intents much more difficult to pull off; discouraging.

Anyway I'm probably not the only one who thinks you're doing a fantastic job answering the many questions that are posted on this list, in great details, regardless of how trivial they are or how confused the poster is.

Instead of you apologising, it should instead be everyone else thanking you for this. So let me start. Thanks!


On 09/19/2016 07:05 AM, [hidden email] wrote:
I have been taken to task in private e-mail by someone
who detected in my response to the "list comprehension puzzle"
both "aggressive sarcasm" and "undisguised contempt".

In all honesty, no sarcasm was intended. (A sarcastic response
would not have pointed to the Erlang reference manual.) Nor
was any contempt whatsoever involved.  I should not have to
reassure long-term readers of this mailing list that these
attitudes my critic claimed to detect were entirely imaginary.

However, it shows that it was possible for people to misread
what I wrote.  If anyone took offence at the message I
*meant* to be helpful, please accept my assurance that no
offence was intended and my unreserved apology for the offence.



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


--
Loïc Hoguin
http://ninenines.eu
Author of The Erlanger Playbook,
A book about software development using Erlang

_______________________________________________
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: Apology

Roger Price-6
In reply to this post by Loïc Hoguin-3
On Mon, 19 Sep 2016, Loïc Hoguin wrote:

> There was obviously no ill intent in that message. ...
>
> Anyway I'm probably not the only one who thinks you're doing a fantastic
> job answering the many questions that are posted on this list, in great
> details, regardless of how trivial they are or how confused the poster is.
>
> On 09/19/2016 07:05 AM, [hidden email] wrote:
>> I have been taken to task in private e-mail by someone
>> who detected in my response to the "list comprehension puzzle"
>> both "aggressive sarcasm" and "undisguised contempt".
When citing the Erlang reference manual section 3.12 is seen as
"aggressive sarcasm" and "undisguised contempt" then this must be the
snowflake generation.  Perhaps section 3.12 needs a trigger warning :-)

A loud and enthusiastic "Thankyou" to ROK for many excellent postings.
I keep a stash of some which I think are outstanding.

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

Re: Apology

Miles Fidelman
On 9/19/16 5:00 AM, Roger Price wrote:

> On Mon, 19 Sep 2016, Loïc Hoguin wrote:
>
>> There was obviously no ill intent in that message. ...
>>
>> Anyway I'm probably not the only one who thinks you're doing a
>> fantastic job answering the many questions that are posted on this
>> list, in great details, regardless of how trivial they are or how
>> confused the poster is.
>>
>> On 09/19/2016 07:05 AM, [hidden email] wrote:
>>> I have been taken to task in private e-mail by someone
>>> who detected in my response to the "list comprehension puzzle"
>>> both "aggressive sarcasm" and "undisguised contempt".
>
> When citing the Erlang reference manual section 3.12 is seen as
> "aggressive sarcasm" and "undisguised contempt" then this must be the
> snowflake generation.  Perhaps section 3.12 needs a trigger warning :-)
>
> A loud and enthusiastic "Thankyou" to ROK for many excellent postings.
> I keep a stash of some which I think are outstanding.
>
Likewise!

Miles Fidelman

p.s.  Personally, I'm a big fan of "aggressive sarcasm" - sometimes it's
more than appropriate.  :-)

--
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: Apology

Robert Wilkinson
In reply to this post by Richard A. O'Keefe-2
On Mon, Sep 19, 2016 at 05:05:52PM +1200, [hidden email] wrote:

> I have been taken to task in private e-mail by someone
> who detected in my response to the "list comprehension puzzle"
> both "aggressive sarcasm" and "undisguised contempt".
>
> In all honesty, no sarcasm was intended. (A sarcastic response
> would not have pointed to the Erlang reference manual.) Nor
> was any contempt whatsoever involved.  I should not have to
> reassure long-term readers of this mailing list that these
> attitudes my critic claimed to detect were entirely imaginary.
>
> However, it shows that it was possible for people to misread
> what I wrote.  If anyone took offence at the message I
> *meant* to be helpful, please accept my assurance that no
> offence was intended and my unreserved apology for the offence.

I would like to add my name to the list of people who are very happy
with the contributions that you make to this mailing list.

Bob

P.S. Fortune cookie random and apposite :-)
--
First law of debate:
        Never argue with a fool.  People might not know the difference.
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Apology

Joe Armstrong-2
In reply to this post by Richard A. O'Keefe-2
Richard

My flabber is gasted.

I read what I assumed the posts that you referred to and am truly
puzzled.

I could not detect anything that I construed as either aggressive
or sarcastic.

I remain very puzzled.

/Joe


On Mon, Sep 19, 2016 at 7:05 AM,  <[hidden email]> wrote:

> I have been taken to task in private e-mail by someone
> who detected in my response to the "list comprehension puzzle"
> both "aggressive sarcasm" and "undisguised contempt".
>
> In all honesty, no sarcasm was intended. (A sarcastic response
> would not have pointed to the Erlang reference manual.) Nor
> was any contempt whatsoever involved.  I should not have to
> reassure long-term readers of this mailing list that these
> attitudes my critic claimed to detect were entirely imaginary.
>
> However, it shows that it was possible for people to misread
> what I wrote.  If anyone took offence at the message I
> *meant* to be helpful, please accept my assurance that no
> offence was intended and my unreserved apology for the offence.
>
>
>
> _______________________________________________
> 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: Apology

Fred Hebert-2
In reply to this post by Richard A. O'Keefe-2
On 09/19, [hidden email] wrote:
>However, it shows that it was possible for people to misread
>what I wrote.  If anyone took offence at the message I
>*meant* to be helpful, please accept my assurance that no
>offence was intended and my unreserved apology for the offence.
>

Without commenting on the level of offensiveness people perceive in your
original post, I want to commend you on what I perceive to be a healthy
and civil response to this.

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

Re: Apology

Jesper Louis Andersen-2
In reply to this post by Joe Armstrong-2
Hi,

Rather than joining the choir outright, I do see the complainers point. Text is a poor medium at communicating intent and there are two ways one can read the post, where one indeed yield sarcasm and snide remarks. Fortunately, there is also intent, and having known Richard's writing for more than 10 years, I can assure you no malice was intended. He even made a post to apologize were it misunderstood. One mans aggresion is another mans Socratic teaching.

Most people mean no harm in their writings. So I'd advise people to err on the side of misunderstanding, rather than on the side of rudeness. Of course, some people are genuinely rude, but they tend to be few and far in between.

Finally, let me second Loïc. There is a current tendency in general internet discourse toward people becoming more sensitive. That is, people err on the opposite side of what I advise above, and take offense at other people's writings whether it was the underlying intent or not. I think this view has a long-term chilling effect on communities:

"I cannot give you the formula for success, but I can give you the formula for failure - which is: Try to please everybody."
  - Herbert Bayard Swope

People are excruciatingly good at finding error with your writings[0]. You better get used to it.

[0] As a regular blog poster, you simply know that once your post hits Hacker News, then there is someone, somewhere, who derives great pleasure and arousal from taking a single sentence--usually out of context--and stabbing it with a knife until it dies. Then, with glee they will rejoice having found you are not only wrong, but bloody inconsistent and factually no better than a brown-speckled slug, whatever that is.


On Mon, Sep 19, 2016 at 6:28 PM, Joe Armstrong <[hidden email]> wrote:
Richard

My flabber is gasted.

I read what I assumed the posts that you referred to and am truly
puzzled.

I could not detect anything that I construed as either aggressive
or sarcastic.

I remain very puzzled.

/Joe


On Mon, Sep 19, 2016 at 7:05 AM,  <[hidden email]> wrote:
> I have been taken to task in private e-mail by someone
> who detected in my response to the "list comprehension puzzle"
> both "aggressive sarcasm" and "undisguised contempt".
>
> In all honesty, no sarcasm was intended. (A sarcastic response
> would not have pointed to the Erlang reference manual.) Nor
> was any contempt whatsoever involved.  I should not have to
> reassure long-term readers of this mailing list that these
> attitudes my critic claimed to detect were entirely imaginary.
>
> However, it shows that it was possible for people to misread
> what I wrote.  If anyone took offence at the message I
> *meant* to be helpful, please accept my assurance that no
> offence was intended and my unreserved apology for the offence.
>
>
>
> _______________________________________________
> 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



--
J.

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

Re: Apology

Lloyd R. Prentice-2
In reply to this post by Richard A. O'Keefe-2
Mea Culpa.

I wrote the PRIVATE post that has led to this thread. And I do apologize to all on this list for whatever unpleasantness it has generated.

As I've noted before, I am not a professional programmer. But I have struggled diligently over the past three years to learn what I need to know to develop a web application in Erlang that is critical to my indie publishing business. And I have many times over been the beneficiary of the expertise and kind generosity of folks on this list. I would never want to do anything to tarnish the good will and ever-helpful spirit that animates the many threads on this list.

No excuse, but I was exhausted after a long and very frustrating day of Erlang programming when I posted my query re: list comprehensions and, subsequently, my private response to ROK's post.

Within minutes of my first posting Dan Gudmundsson responded succinctly and insightfully. It was helpful and I thanked him.

Then ROK's response popped up. The tone was quite contrary to Dan's. Perhaps there was/is projection on my part. But here are lines that set me off:

--- "The documentation is very clear:"

This line sounded to me like so many I've read on other programming threads: "Read the f___king documentation...", "Read the documentation stupid." Fact is I have and continue to spend hours and hours reading the Erlang documentation and much of it is still not clear to me.

--- "Why would you ever have thought that S *might* be an integer? If you want a hexadecimal integer, section 3.2 is clear."

Well, sorry, but in the heat and fatigue of trying to solve a problem I did not read section 3.2. And in reading it now it's not all that clear to me. But more, I knew S was not an integer. I was merely confirming it for sake of making my question as clear as possible. But, clearly, I wasn't clear enough.

This is an outstanding example of how easily brief text exchanges can be misconstrued on the Internet. Hexadecimal integers never crossed my mind.

-- "That would require us to read your mind. What did you expect to happen and why did you expect that?"

Once again, this sounded in context like an admonishment from a middle school algebra teacher to a dense student. Dense I'll admit to. But my algebra days are far behind me.

ROK then continues with Prolog and Haskell examples. By this point in the post it came across to me as "look how clever I am and you're not."

In short, I'll apologize here publicly for my, perhaps, intemperate response to ROK.

But I won't apologize for my motive:

The tone of expert-to-noobie communication is a critical factor in fostering a vibrant programming community. I quite disagree that "aggressive sarcasm" is an appropriate pedagogical strategy.

While I'm beyond the noobie phase, I do care deeply about the future of Erlang. And my reading of ROK's post, which admittedly may have been projection, came across with the kind of tone that, I fear, would turn noobies away.

Best wishes to all,

Lloyd


*********************************************
My books:

THE GOSPEL OF ASHES
http://thegospelofashes.com

Strength is not enough. Do they have the courage
and the cunning? Can they survive long enough to
save the lives of millions?  

FREEIN' PANCHO
http://freeinpancho.com

A community of misfits help a troubled boy find his way

AYA TAKEO
http://ayatakeo.com

Star-crossed love, war and power in an alternative
universe

Available through Amazon or by request from your
favorite bookstore


**********************************************

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

Re: Apology

Loïc Hoguin-3
 From reading ROK's post I get the feeling that he did not understand
what you were trying to figure out, and so attempted to provide a
detailed answer about every point. Reconstruct your thougths in hopes of
clarifying things for you.

ROK's questions may sound offensive. They're not. Sometimes we jump to
conclusions without asking ourselves those questions. Sometimes they're
even stupid questions. Yet we need to be reminded of those because it's
only when asking the right questions that we correct our understanding.

As for the documentation being very clear, it's very subjective. Nothing
is ever "very clear" to everyone.

On 09/19/2016 09:22 PM, [hidden email] wrote:

> Mea Culpa.
>
> I wrote the PRIVATE post that has led to this thread. And I do apologize to all on this list for whatever unpleasantness it has generated.
>
> As I've noted before, I am not a professional programmer. But I have struggled diligently over the past three years to learn what I need to know to develop a web application in Erlang that is critical to my indie publishing business. And I have many times over been the beneficiary of the expertise and kind generosity of folks on this list. I would never want to do anything to tarnish the good will and ever-helpful spirit that animates the many threads on this list.
>
> No excuse, but I was exhausted after a long and very frustrating day of Erlang programming when I posted my query re: list comprehensions and, subsequently, my private response to ROK's post.
>
> Within minutes of my first posting Dan Gudmundsson responded succinctly and insightfully. It was helpful and I thanked him.
>
> Then ROK's response popped up. The tone was quite contrary to Dan's. Perhaps there was/is projection on my part. But here are lines that set me off:
>
> --- "The documentation is very clear:"
>
> This line sounded to me like so many I've read on other programming threads: "Read the f___king documentation...", "Read the documentation stupid." Fact is I have and continue to spend hours and hours reading the Erlang documentation and much of it is still not clear to me.
>
> --- "Why would you ever have thought that S *might* be an integer? If you want a hexadecimal integer, section 3.2 is clear."
>
> Well, sorry, but in the heat and fatigue of trying to solve a problem I did not read section 3.2. And in reading it now it's not all that clear to me. But more, I knew S was not an integer. I was merely confirming it for sake of making my question as clear as possible. But, clearly, I wasn't clear enough.
>
> This is an outstanding example of how easily brief text exchanges can be misconstrued on the Internet. Hexadecimal integers never crossed my mind.
>
> -- "That would require us to read your mind. What did you expect to happen and why did you expect that?"
>
> Once again, this sounded in context like an admonishment from a middle school algebra teacher to a dense student. Dense I'll admit to. But my algebra days are far behind me.
>
> ROK then continues with Prolog and Haskell examples. By this point in the post it came across to me as "look how clever I am and you're not."
>
> In short, I'll apologize here publicly for my, perhaps, intemperate response to ROK.
>
> But I won't apologize for my motive:
>
> The tone of expert-to-noobie communication is a critical factor in fostering a vibrant programming community. I quite disagree that "aggressive sarcasm" is an appropriate pedagogical strategy.
>
> While I'm beyond the noobie phase, I do care deeply about the future of Erlang. And my reading of ROK's post, which admittedly may have been projection, came across with the kind of tone that, I fear, would turn noobies away.
>
> Best wishes to all,
>
> Lloyd
>
>
> *********************************************
> My books:
>
> THE GOSPEL OF ASHES
> http://thegospelofashes.com
>
> Strength is not enough. Do they have the courage
> and the cunning? Can they survive long enough to
> save the lives of millions?
>
> FREEIN' PANCHO
> http://freeinpancho.com
>
> A community of misfits help a troubled boy find his way
>
> AYA TAKEO
> http://ayatakeo.com
>
> Star-crossed love, war and power in an alternative
> universe
>
> Available through Amazon or by request from your
> favorite bookstore
>
>
> **********************************************
>
> _______________________________________________
> erlang-questions mailing list
> [hidden email]
> http://erlang.org/mailman/listinfo/erlang-questions
>

--
Loïc Hoguin
http://ninenines.eu
Author of The Erlanger Playbook,
A book about software development using Erlang
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Apology

Sashan Govender
In reply to this post by Richard A. O'Keefe-2
One of the things I've learned when writing responses to questions is
not to use rhetorical questions. For example 'what do you think?' can
come across as condescending, depending on the reader, and especially
if you have spent 4 hours at home thinking about this after working 8
hours in your day job. Personally mailing lists and forums are the
last place I go to find and answer and I only use them when I've
exhausted my will to find the answer elsewhere, either by reading
documentation, writing some test code, or reading someone else's code.
Almost all those options are preferable to me. Additionally people on
this list are not the type of people to have not tried. They are on
this list out of curiosity and interest in Erlang, so by default you
should assume that they have thought about the problem before posting
to the list. Rhetorical questions work better in a face to face
dialogue when trying to employ the Socratic method (for example see
here: http://www.garlikov.com/Soc_Meth.html) to elicit from the other
person what they might already know but haven't realized, however, in
a face to face dialogue the tone in the voice also carries meaning and
a question like 'what do you think?' in that context comes with a tone
that is lost in a written email. Asked in person, a question like
'what do you think?' conveys that you value that person's opinion. In
an email, the tone of voice isn't there and the question can be
misconstrued.

Avoid subjective statements like 'the documentation is very clear'. It
doesn't add anything and doesn't serve any purpose. The person asking
the question wouldn't have asked if it was 'very clear'. To be honest,
it's pretty similar to RTFM.

'That would require us to read your mind' is contradictory given that
you engaged in mind reading a few sentences above with "Why would you
ever have thought that S *might* be an integer?" It's also reminiscent
of something similar to what the alpha geeks at school would have said
behind a snigger, but that's just my perception, biased by my personal
life experience. Phrases that work as jokes in real life amongst
friends lose their meaning on mailing lists with strangers.


On Mon, Sep 19, 2016 at 3:05 PM,  <[hidden email]> wrote:

> I have been taken to task in private e-mail by someone
> who detected in my response to the "list comprehension puzzle"
> both "aggressive sarcasm" and "undisguised contempt".
>
> In all honesty, no sarcasm was intended. (A sarcastic response
> would not have pointed to the Erlang reference manual.) Nor
> was any contempt whatsoever involved.  I should not have to
> reassure long-term readers of this mailing list that these
> attitudes my critic claimed to detect were entirely imaginary.
>
> However, it shows that it was possible for people to misread
> what I wrote.  If anyone took offence at the message I
> *meant* to be helpful, please accept my assurance that no
> offence was intended and my unreserved apology for the offence.
>
>
>
> _______________________________________________
> 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: Apology

Richard A. O'Keefe-2
In reply to this post by Loïc Hoguin-3


On 20/09/16 8:18 AM, Loïc Hoguin wrote:
>>
> As for the documentation being very clear, it's very subjective. Nothing
> is ever "very clear" to everyone.

Fair point.
There are actually two issues, of course.

FINDING the documentation is the first thing.
Searching for "Erlang documentation" quickly turns up
https://www.erlang.org/docs.
That says
   <a>Erlang Reference Manual - User's Guide</a>
   A user's guide System principles and efficiency guide
which looks like an editing error.  If you follow the
link you find the reference manual, not the system
principles or efficiency guide.
A reference manual and user's guide being different
things, it would be better if this said something like

   <a>Erlang Reference Manual</a>
   Defines Erlang's syntax, built-in data types,
   preprocessor, error handling, processes, and more.

It would also be better if when you clicked on the link
it didn't say

   Erlang Reference Manual User's Guide

(which sounds like a user's guide to using the reference
manual) but something like

   Erlang Reference Manual
   {An abstract}

because the eye is drawn to the big blank space where
there's just a copyright notice, rather than to the navbar.
I can't speak for anyone else, but whenever I go to that
page I have several nervous seconds while wondering if I've
come to the right place.

I personally find it confusing that "Escape Sequences"
comes after "Boolean" rather than after "String" or "Atom".

Perhaps the most helpful thing in
https://www.erlang.org/docs
is
   <a>Learn You Some Erlang for Great Good!<a>
   Learn You Some Erlang for Great Good! by Fred Hebert
   is a beginner's book about Erlang, published in 2013.
   It is available in paper copies and online.

I have a copy of that book.  While it is a good book
for beginners, it isn't just for beginners.  I have to
be honest here: when it first came out I *hated* the
title.  Stupid, stupid, stupid.  "Don't judge a book
by its cover!"  Actually reading the book taught me,
well, not exactly stuff I hadn't found elsewhere, but
how to *use* a lot of stuff I hadn't bothered with.
Someone who reads that book will not be a beginner for long.

We are blessed with a lot of good books about Erlang.
I don't want to rank them.  But I do think that the
documentation page might want to draw special attention
to this book because people CAN read it on-line.  For
example, three clicks get to you an explanation of strings.

The second issue is UNDERSTANDING the documentation when
you find it.  The problem for writers is striking a
balance between being concise and being patronising.
I remember putting a lot of effort into writing a
document for the BSI/ISO Prolog committee explaining a
particular issue and some alternatives, and being told
that it had been completely ignored because it was too
long.  There's a series of books, originally "The Little
Lisper" which I personally experienced as offensively
patronising (and so culture-bound it wasn't funny, though
it tried to be).  Yet for many people it was an EXCELLENT
introduction to Lisp and Scheme and they loved the humour.

The current reference manual tries to be reassuringly
informal (for beginners) and timesavingly brief (for
experienced users).  Perhaps these rôles should be
split between two different documents?  Or maybe an
idea from MTW https://en.wikipedia.org/wiki/Gravitation_(book)
could be adopted:  the text of that book is divided into
"Track 1" (beginner level) and "Track 2" (more advanced)
and the corners of the pages are coloured so you know which
is which.  (About 35 years after buying it, I'm still on
track 1.  Sigh.  It's a great book for long flights: I am
guaranteed *never* to finish it.  Sigh.)

Hey, maybe we could get Fred Hébert to write the
"Erlang Reference Manual for Beginners" (:-).
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Apology

Lloyd R. Prentice-2
So, I'm relieved and pleased that this thread is veering in a constructive direction. And I salute Richard for giving it a nudge.

Erlang documentation has been a frequent topic of conversation for as long as I've been following this list. On the one hand colossal work has been invested by many to produce what we have. I, for one, extend hearty thanks. On the other hand, many of us find nitpicks that loom large when we're trying to solve a problem, turn to the docs, but don't find the guidance we're looking for and need. Given my limited programming experience, the docs have been far more helpful than not, but four things have now and again vexed me:

1. Lack of context; e.g. why a library or function is useful; what real world problems can I solve with it? In some cases there is discussion, but so technical it flies over my head.

2. Excessive abstraction/concision. This is great for folks with mathematics training and cast of mind. But my literary sensibilities go tilt.

3. Too few or less-than-clear illustrative code fragments

4. Insufficient guidance on how to think through and design non-trivial Erlang programs.

In some areas it feels like the docs were written to REMIND users of what they already know, e.g. as reference rather than teaching material. So, no doubt every one of my vexations may well reflect my personal lack of experience with both Erlang and other programming languages.

So we're left with two hard problems:

1. What should we assume about the consumers of Erlang documentation? Perhaps these assumptions should be explicit throughout the docs.

2. How can we iteratively improve the docs given voluntary resources and busy lives?

One hypothesis:

1. Writing software documentation that serves every consumer and every need may well be an impossible task.

I have purchased and studied every one of the Erlang books and taken much from each of them. I also often search for tutorials to help understand this issue or that. But I think it's safe to assume that official Erlang docs are the first go-to place for folks with immediate questions that need answers.

And one last question:

1. Can improved documentation be an effective tool for expanding and invigorating the Erlang community?

All the best,

Lloyd


Sent from my iPad

> On Sep 19, 2016, at 10:26 PM, Richard A. O'Keefe <[hidden email]> wrote:
>
>
>
> On 20/09/16 8:18 AM, Loïc Hoguin wrote:
>> As for the documentation being very clear, it's very subjective. Nothing
>> is ever "very clear" to everyone.
>
> Fair point.
> There are actually two issues, of course.
>
> FINDING the documentation is the first thing.
> Searching for "Erlang documentation" quickly turns up
> https://www.erlang.org/docs.
> That says
>  <a>Erlang Reference Manual - User's Guide</a>
>  A user's guide System principles and efficiency guide
> which looks like an editing error.  If you follow the
> link you find the reference manual, not the system
> principles or efficiency guide.
> A reference manual and user's guide being different
> things, it would be better if this said something like
>
>  <a>Erlang Reference Manual</a>
>  Defines Erlang's syntax, built-in data types,
>  preprocessor, error handling, processes, and more.
>
> It would also be better if when you clicked on the link
> it didn't say
>
>  Erlang Reference Manual User's Guide
>
> (which sounds like a user's guide to using the reference
> manual) but something like
>
>  Erlang Reference Manual
>  {An abstract}
>
> because the eye is drawn to the big blank space where
> there's just a copyright notice, rather than to the navbar.
> I can't speak for anyone else, but whenever I go to that
> page I have several nervous seconds while wondering if I've
> come to the right place.
>
> I personally find it confusing that "Escape Sequences"
> comes after "Boolean" rather than after "String" or "Atom".
>
> Perhaps the most helpful thing in
> https://www.erlang.org/docs
> is
>  <a>Learn You Some Erlang for Great Good!<a>
>  Learn You Some Erlang for Great Good! by Fred Hebert
>  is a beginner's book about Erlang, published in 2013.
>  It is available in paper copies and online.
>
> I have a copy of that book.  While it is a good book
> for beginners, it isn't just for beginners.  I have to
> be honest here: when it first came out I *hated* the
> title.  Stupid, stupid, stupid.  "Don't judge a book
> by its cover!"  Actually reading the book taught me,
> well, not exactly stuff I hadn't found elsewhere, but
> how to *use* a lot of stuff I hadn't bothered with.
> Someone who reads that book will not be a beginner for long.
>
> We are blessed with a lot of good books about Erlang.
> I don't want to rank them.  But I do think that the
> documentation page might want to draw special attention
> to this book because people CAN read it on-line.  For
> example, three clicks get to you an explanation of strings.
>
> The second issue is UNDERSTANDING the documentation when
> you find it.  The problem for writers is striking a
> balance between being concise and being patronising.
> I remember putting a lot of effort into writing a
> document for the BSI/ISO Prolog committee explaining a
> particular issue and some alternatives, and being told
> that it had been completely ignored because it was too
> long.  There's a series of books, originally "The Little
> Lisper" which I personally experienced as offensively
> patronising (and so culture-bound it wasn't funny, though
> it tried to be).  Yet for many people it was an EXCELLENT
> introduction to Lisp and Scheme and they loved the humour.
>
> The current reference manual tries to be reassuringly
> informal (for beginners) and timesavingly brief (for
> experienced users).  Perhaps these rôles should be
> split between two different documents?  Or maybe an
> idea from MTW https://en.wikipedia.org/wiki/Gravitation_(book)
> could be adopted:  the text of that book is divided into
> "Track 1" (beginner level) and "Track 2" (more advanced)
> and the corners of the pages are coloured so you know which
> is which.  (About 35 years after buying it, I'm still on
> track 1.  Sigh.  It's a great book for long flights: I am
> guaranteed *never* to finish it.  Sigh.)
>
> Hey, maybe we could get Fred Hébert to write the
> "Erlang Reference Manual for Beginners" (:-).
> _______________________________________________
> 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: Apology

Luke
Good documentation is designed for readability, that goes beyond just content - it includes layout, organisation and definitely aesthetics. The Erlang docs are a virtualized printout, not an interactive guide on how to use a programming language.

Look at the difference in these two pages. 


vs


Why doesn't anyone ever mention that the docs just look crap? It's easy to fix, and would make a massive difference on the impression new devs get about Erlang. These days programmers have largely become accustomed to a certain look and feel, and have an intuition on how to dig for what they're trying to find which doesn't stem from a time when you would turn to the back of the printout and scan down the index, apologies to the E/// greybeards in the list :P

The underlying issue of terse or inadequate explanation would take longer to fix, I think allowing pull requests would be a big step forward. Also, what's with the multiple PDFs - you have a user manual, getting started guide, reference manual, probably more that I can't remember right now. There has got to be a way to just combine these into a single portal that all developers can refer back to. 

Lots of good information has been kept in this mailing list, so mails from it often come up in Google. Tell me, how quickly did you find the answer on this page http://erlang.org/pipermail/erlang-questions/2007-May/026655.html compared to this one http://stackoverflow.com/questions/2065990/defining-erlang-functions-in-the-shell

I'm not a novice programmer - I had been coding for 10 years when I picked up Erlang with a masters in Software Eng, and immediately fell in love with the language, but with such an expert community behind it I think it's been a while since somebody who didn't intimately understand everything about Erlang in detail gave feedback on the experience for new developers.

On Tue, Sep 20, 2016 at 2:38 PM, Lloyd R. Prentice <[hidden email]> wrote:
So, I'm relieved and pleased that this thread is veering in a constructive direction. And I salute Richard for giving it a nudge.

Erlang documentation has been a frequent topic of conversation for as long as I've been following this list. On the one hand colossal work has been invested by many to produce what we have. I, for one, extend hearty thanks. On the other hand, many of us find nitpicks that loom large when we're trying to solve a problem, turn to the docs, but don't find the guidance we're looking for and need. Given my limited programming experience, the docs have been far more helpful than not, but four things have now and again vexed me:

1. Lack of context; e.g. why a library or function is useful; what real world problems can I solve with it? In some cases there is discussion, but so technical it flies over my head.

2. Excessive abstraction/concision. This is great for folks with mathematics training and cast of mind. But my literary sensibilities go tilt.

3. Too few or less-than-clear illustrative code fragments

4. Insufficient guidance on how to think through and design non-trivial Erlang programs.

In some areas it feels like the docs were written to REMIND users of what they already know, e.g. as reference rather than teaching material. So, no doubt every one of my vexations may well reflect my personal lack of experience with both Erlang and other programming languages.

So we're left with two hard problems:

1. What should we assume about the consumers of Erlang documentation? Perhaps these assumptions should be explicit throughout the docs.

2. How can we iteratively improve the docs given voluntary resources and busy lives?

One hypothesis:

1. Writing software documentation that serves every consumer and every need may well be an impossible task.

I have purchased and studied every one of the Erlang books and taken much from each of them. I also often search for tutorials to help understand this issue or that. But I think it's safe to assume that official Erlang docs are the first go-to place for folks with immediate questions that need answers.

And one last question:

1. Can improved documentation be an effective tool for expanding and invigorating the Erlang community?

All the best,

Lloyd


Sent from my iPad

> On Sep 19, 2016, at 10:26 PM, Richard A. O'Keefe <[hidden email]> wrote:
>
>
>
> On 20/09/16 8:18 AM, Loïc Hoguin wrote:
>> As for the documentation being very clear, it's very subjective. Nothing
>> is ever "very clear" to everyone.
>
> Fair point.
> There are actually two issues, of course.
>
> FINDING the documentation is the first thing.
> Searching for "Erlang documentation" quickly turns up
> https://www.erlang.org/docs.
> That says
>  <a>Erlang Reference Manual - User's Guide</a>
>  A user's guide System principles and efficiency guide
> which looks like an editing error.  If you follow the
> link you find the reference manual, not the system
> principles or efficiency guide.
> A reference manual and user's guide being different
> things, it would be better if this said something like
>
>  <a>Erlang Reference Manual</a>
>  Defines Erlang's syntax, built-in data types,
>  preprocessor, error handling, processes, and more.
>
> It would also be better if when you clicked on the link
> it didn't say
>
>  Erlang Reference Manual User's Guide
>
> (which sounds like a user's guide to using the reference
> manual) but something like
>
>  Erlang Reference Manual
>  {An abstract}
>
> because the eye is drawn to the big blank space where
> there's just a copyright notice, rather than to the navbar.
> I can't speak for anyone else, but whenever I go to that
> page I have several nervous seconds while wondering if I've
> come to the right place.
>
> I personally find it confusing that "Escape Sequences"
> comes after "Boolean" rather than after "String" or "Atom".
>
> Perhaps the most helpful thing in
> https://www.erlang.org/docs
> is
>  <a>Learn You Some Erlang for Great Good!<a>
>  Learn You Some Erlang for Great Good! by Fred Hebert
>  is a beginner's book about Erlang, published in 2013.
>  It is available in paper copies and online.
>
> I have a copy of that book.  While it is a good book
> for beginners, it isn't just for beginners.  I have to
> be honest here: when it first came out I *hated* the
> title.  Stupid, stupid, stupid.  "Don't judge a book
> by its cover!"  Actually reading the book taught me,
> well, not exactly stuff I hadn't found elsewhere, but
> how to *use* a lot of stuff I hadn't bothered with.
> Someone who reads that book will not be a beginner for long.
>
> We are blessed with a lot of good books about Erlang.
> I don't want to rank them.  But I do think that the
> documentation page might want to draw special attention
> to this book because people CAN read it on-line.  For
> example, three clicks get to you an explanation of strings.
>
> The second issue is UNDERSTANDING the documentation when
> you find it.  The problem for writers is striking a
> balance between being concise and being patronising.
> I remember putting a lot of effort into writing a
> document for the BSI/ISO Prolog committee explaining a
> particular issue and some alternatives, and being told
> that it had been completely ignored because it was too
> long.  There's a series of books, originally "The Little
> Lisper" which I personally experienced as offensively
> patronising (and so culture-bound it wasn't funny, though
> it tried to be).  Yet for many people it was an EXCELLENT
> introduction to Lisp and Scheme and they loved the humour.
>
> The current reference manual tries to be reassuringly
> informal (for beginners) and timesavingly brief (for
> experienced users).  Perhaps these rôles should be
> split between two different documents?  Or maybe an
> idea from MTW https://en.wikipedia.org/wiki/Gravitation_(book)
> could be adopted:  the text of that book is divided into
> "Track 1" (beginner level) and "Track 2" (more advanced)
> and the corners of the pages are coloured so you know which
> is which.  (About 35 years after buying it, I'm still on
> track 1.  Sigh.  It's a great book for long flights: I am
> guaranteed *never* to finish it.  Sigh.)
>
> Hey, maybe we could get Fred Hébert to write the
> "Erlang Reference Manual for Beginners" (:-).
> _______________________________________________
> 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


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

Erlang documentation (was: Apology)

Kenneth Lakin
On 09/19/2016 10:07 PM, Luke wrote:
> Why doesn't anyone ever mention that the docs just look crap?

I'm fond of how the docs look and -for the most part- reasonably pleased
with how they're organized. (In particular, the /doc/man/$MODULE.html
structure is _absolutely killer_ for reference documentation.) IMO, the
quality and general completeness of the Erlang reference manuals is what
most projects should strive to emulate in their API documentation.

> These days programmers have largely become accustomed to a
> certain look and feel...

I _really_ don't like how a _lot_ of "modern" documentation is laid out.
If you're looking for inspiration, a _really_ impressive reference
manual + user's guide (that -undoubtedly- took a _ton_ of work to put
together) is the Postgresql documentation.

> I think allowing pull requests would be a big step forward.

https://github.com/erlang/otp/pulls

I know for a fact that documentation updates are accepted. :)



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

signature.asc (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Apology

Loïc Hoguin-3
In reply to this post by Luke
On 09/20/2016 07:07 AM, Luke wrote:
> Look at the difference in these two pages.
>
> http://erlang.org/doc/design_principles/applications.html
>
> vs
>
> http://elixir-lang.org/docs/stable/elixir/Application.html
>
> Why doesn't anyone ever mention that the docs just look crap?

You're comparing a user guide page from Erlang to a function reference
page from Elixir. The equivalent Erlang page is
http://erlang.org/doc/man/application.html

And I'll echo Kenneth, the Erlang one is definitely better in my
opinion. I'm not even sure why the function is described twice in the
Elixir docs (title and spec). And not needing to go back at the top to
select another function is very convenient.

--
Loïc Hoguin
http://ninenines.eu
Author of The Erlanger Playbook,
A book about software development using Erlang
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Apology

Benoit Chesneau-2
without counting we have erldocs.com
On Tue, 20 Sep 2016 at 09:00, Loïc Hoguin <[hidden email]> wrote:
On 09/20/2016 07:07 AM, Luke wrote:
> Look at the difference in these two pages.
>
> http://erlang.org/doc/design_principles/applications.html
>
> vs
>
> http://elixir-lang.org/docs/stable/elixir/Application.html
>
> Why doesn't anyone ever mention that the docs just look crap?

You're comparing a user guide page from Erlang to a function reference
page from Elixir. The equivalent Erlang page is
http://erlang.org/doc/man/application.html

And I'll echo Kenneth, the Erlang one is definitely better in my
opinion. I'm not even sure why the function is described twice in the
Elixir docs (title and spec). And not needing to go back at the top to
select another function is very convenient.

--
Loïc Hoguin
http://ninenines.eu
Author of The Erlanger Playbook,
A book about software development using Erlang
_______________________________________________
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: Apology

Loïc Hoguin-3
In reply to this post by Lloyd R. Prentice-2
On 09/20/2016 06:38 AM, Lloyd R. Prentice wrote:
> 4. Insufficient guidance on how to think through and design non-trivial Erlang programs.

This is the main problem with Erlang documentation. We have great
reference manuals. We have good user guides (between bad and great
depending on the application, but mostly good). We have virtually no
tutorials outside books.

I recommend reading this and fully understanding it when talking about
documentation: https://jacobian.org/writing/great-documentation/

In particular the first part, what to write, describes what is expected
from each and how they help.

--
Loïc Hoguin
http://ninenines.eu
Author of The Erlanger Playbook,
A book about software development using Erlang
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Erlang documentation (was: Apology)

Roger Lipscombe-2
In reply to this post by Kenneth Lakin
On 20 September 2016 at 07:13, Kenneth Lakin <[hidden email]> wrote:
> I'm fond of how the docs look and -for the most part- reasonably pleased
> with how they're organized. (In particular, the /doc/man/$MODULE.html
> structure is _absolutely killer_ for reference documentation.)

I *do* wish that -- somehow -- the docs could be marked up so that a
Google search would jump directly to the appropriate function.

Some of the pages *almost* work: searching for "erlang element"
returns the erlang(3) page, with (in the snippet) direct links to
(e.g.) erlang:system_flag(dirty_cpu_schedulers_online). This is wrong,
but encouraging (inasmuch as it says that Google understands anchors,
and that some extra tags might fix it).

On the other hand, searching for "erlang lists flatmap" takes you only
to the top of the "lists" page.

I have no idea how to make this work, however.
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
1234 ... 9