[Haskell-cafe] Haskell's "historical futurism" needs better writing, not better tools

[Michael Turner]

And I forgot to add: selling power is important, but clarity is too.
Selling ergonomics is important, but clarity is too.

I once learned a very, very powerful language: APL. Now, to be sure,
there was a market obstacle -- it had a very extended character set.
But IBM probably thought, "A very powerful language will sell! And
that means we'll sell a lot more of the specialized IBM Selectric
type-balls! This could be our most profitable programming language
ever, especially considering that type-balls wear out eventually and
have to be replaced! What's not to like?" I suppose you could say APL
was ergonomic, because you spent a lot of your keyboard time just
looking for the right keytop symbol, and it slowed you way down.

The thing is, most code that actually gets used, and even makes money,
is read more than it's written. Software expense is mostly in the
maintenance life-cycle, and I think that's still true, even in these
days of Agile and CI -- it's just that the effort of the former
"maintenance phase" bleeds more into the early phases. I'd love to be
so fluent in Haskell that I can appreciate its superior ergonomics,
and I speak as a former RSI casualty. But frustration over feeling
powerless every time GHC barfs out another error message you don't
understand only leads to muscle tension which can inflame chronic RSI,
and Haskell is pretty frustrating, starting out. Of course, I'm sure
people will tell me to just relax and take my time. But I have a lot
of other things to do.

I've noticed an interesting metric for Haskell: github activity is
more sharply distributed over weekend days than just about any other
language in the top 40. Is it basically an intellectual hobby
language, outside of academia? I'm evaluating Haskell for a project,
one for which I'd like to report some serious progress by the time a
certain conference rolls around in March. Months ago, I started with
some confidence that I'd have settled the question. Maybe I'd even
have a demo all written in Haskell by March, if Haskell seemed right.
I'm far less confident now.

I'd been warned that the learning curve is steep and long. If my
complaints about documentation sound anguished, it's for a reason: a
lot of the problems of getting traction on the slope trace back (for
me, at least) to writing by people so steeped in Haskell that they no
longer remember how they themselves absorbed it, the better to explain
it. And, as Simon Peyton-Jones says in one talk, in the early years,
the language designers had the incredible luxury of academia -- as he
admits, they could spend literally years being confused about the
right path forward, at various points, and it didn't matter much for
their careers or their goals. That's years of steeping too. And it
shows. I don't have years. I have months. And lots of other things I
have to get done.

Regards,
Michael Turner
Executive Director
Project Persephone
1-25-33 Takadanobaba
Shinjuku-ku Tokyo 169-0075
Mobile: +81 (90) 5203-8682
turner at projectpersephone.org

Understand - http://www.projectpersephone.org/
Join - http://www.facebook.com/groups/ProjectPersephone/
Donate - http://www.patreon.com/ProjectPersephone
Volunteer - https://github.com/ProjectPersephone

"Love does not consist in gazing at each other, but in looking outward
together in the same direction." -- Antoine de Saint-Exupéry

On Fri, Sep 17, 2021 at 11:27 AM Michael Turner
<michael.eugene.turner at gmail.com> wrote:
>
> On Fri, Sep 17, 2021 at 5:52 AM Viktor Dukhovni <ietf-dane at dukhovni.org> wrote:
> >
> > On Wed, Sep 15, 2021 at 04:07:38PM +0900, Michael Turner wrote:
> >
> > > The real problem is that the writing sucks. [snip]
>
> Vikor:
> > Can you be a bit more specific about which sort of writing you find
> > sufficiently unsatisfactory to say "the writing sucks"?
>
> It's an axiom of sales: quality is what the customer says it is.
> You'll evaluate writing differently depending on what sort of audience
> you're in.
>
> I'm in this audience:
>
> -- I have a lot of programming experience with a variety of languages.
> I have limited patience with writing that feels like it's talking down
> to me.
>
> -- I have limited patience for a language whose main appeal seems to
> be to a niche audience of programmers who want to learn a language in
> part because they've been told it's a challenge -- I'm not seeking
> status among other programmers. ("Ooh, he knows Haskell. You have to
> be really smart to write Haskell.")
>
> -- I prefer a presentation that's clear and concise, with a
> significant reliance on diagrams that show conceptual relations. A
> picture of how something works is worth a thousand words that tell me
> how great something was, or how great it's going to be once I'm
> proficient.
>
> >
> >     * Books about Haskell
> >       - Introductory (e.g. http://learnyouahaskell.com/)
>
> I started here. I was initially drawn in by the welcoming chattiness.
> It got old, fast. Fonzie? Really? How many young programmers today
> even know the TV series Happy Days? Waste of page-space. (But see
> above -- that's MY reaction. Audiences will differ.)
>
> >       - Comprehensive (e.g. the classic Real World Haskell)
>
> I hadn't looked at this before. So I looked today.
>
> Uh-oh: the introductory part reminds me of that old joke about the IBM
> salesman, back in the mainframe days, when getting a computer up and
> running the customer's application could take months, from hardware
> order to production data processing: The salesman sits on the edge of
> the bed on his honeymoon night, telling his bride out great it's going
> to be.
>
> The first bit of code shows how you'd write a very short function
> (courtesy of "take", not of any inherent feature of Haskell's
> programming model) to get the k least elements in a list. A claim is
> made: it's faster because of laziness.
>
> Um, really? Sorting is O(n log n) upper bound no matter what. There's
> a vaguely game-theoretic proof of this I found delightful back in
> college, and it came to mind when I read that. How would you arrange
> numbers in a list so that, no matter what sort algorithm you used,
> there would be no way in general to get the k smallest elements
> without a full sort? Well, maybe the authors mean "faster on average,
> counting using the number of comparisons"? Oh, but wait: isn't there
> some overhead for implementing laziness? Hm, why aren't they saying
> something here?
>
> My eyes glaze over all the IBM salesman honeymoon bridal suite talk,
> so I go to chapter one. I skip through all the stuff I already know,
> and at the end of the chapter, there's bit of code: count the number
> of lines in input. After months of looking at Haskell code (but a few
> weeks of not looking at it) I can't quite get it, the way I'd almost
> instantly get it if it was written in a more conventional programming
> language. It's just an exercise in putting some code in a file and
> running it. Supposedly it will build confidence. It has the opposite
> effect on me. But maybe it's explicated in the next chapter?
>
> I turn to chapter two, hoping that the line-counter would be
> explicated. Oh no: long IBM honeymoon-night salesman talk about Why
> Types Are Good. Oh, fuck you! I already know why types are good! I
> even know what's bad about the otherwise-good type systems of several
> programming languages! WHY ARE YOU WASTING MY TIME?!
>
> >       - Topic focused (e.g. the IMHO rather excellent Parallel and
> >         Concurrent Haskell)
>
> It may be excellent if you're already up to speed on Haskell. I'm a
> newbie drowning in writing that's not for me.
>
> >       - Theory focused (e.g.
> >         https://bartoszmilewski.com/category/category-theory/)
>
> I bailed halfway through a video from Philip Wadler, a talk about
> Categories for the Working Hacker (or something) because he still
> hadn't said anything about how knowing category theory was useful to,
> uh, you know, a working hacker? I ran across a blog that said: forget
> category theory. It won't help you. At least not starting out.
>
> >     * The library reference documentation?
>
> Pretty impenetrable for a newbie, though that's hardly unusual for a
> newbie to any language, with reference docs.
>
> >     * The GHC User's Guide?
>
> Been a while since I looked at it, but not much easier, as I remember.
>
> >     * The Haskell report?
>
> Haven't read it.
>
> >     * Blog posts?
>
> So far, only helpful when they are honest and tell me that I'm having
> trouble for some very good reasons. I feel less alone. I feel less
> stupid.
>
> >     * The Haskell Wiki?
>
> Very sloppy, much neglected. I put in some improvements to articles,
> but a certain syndrome is very much in evidence: it seems mostly
> written by Haskell experts who can't seem to get back into a newbie
> mindset (and who maybe never had a mindset like mine), and who often
> jump from IBM honeymoon salesman talk straight into unnecessarily
> complex examples.
>
> >     * r/haskell?
>
> Sometimes helpful.
>
> >     * Haskell mailing lists?
>
> When you're being told curtly, "Learn lambda calculus", or someone
> can't answer your question about something but instead of saying "I
> don't know where you'd find that", gives you an answer to a question
> you didn't ask, you're not on a truly beginner-friendly newbies list.
> Other mailing lists take up topics that feel way over my head at this
> point.
>
> >     * All of the above???
>
> So far, pretty much.
>
> > I am also curious whether I'm part of the solution or part of the
> > precipitate.  I've recently contributed new documentation for
> > Data.Foldable and Data.Traversable:
> >
> >     https://dnssec-stats.ant.isi.edu/~viktor/haskell/docs/libraries/base/Data-Foldable.html#g:7
> >     https://dnssec-stats.ant.isi.edu/~viktor/haskell/docs/libraries/base/Data-Traversable.html#g:4
>
> OK:
>
> "Merging the contribution of the current element with an accumulator
> value from a partial result is performed by an operator function,
> either explicitly provided by the caller as in foldr, implicit count
> as in length, or partly implicit as in foldMap (where each element is
> mapped into a Monoid, and the monoid's mappend operator performs the
> merge)."
>
> Let me tell you how I tried to read that lo-o-ong sentence.
>
> "Merging the contribution of the current element--"
>
> Um, you didn't introduce "current element", so "the current element"
> is confusing. It feels like you're starting in the middle. And wait,
> is the current element being merged, or is some kind of contribution
> /from/ the current element being merged? I guess since Haskell is
> lazy, it could be the latter . . .
>
> "--with an accumulator value--"
>
> Coming from Erlang, I just call them "accumulators". So is an
> accumulator value different from an accumulator or . . . what?
>
> "--from a partial result--"
>
> So, it's a partial result in the form of the accumulator? Or "the
> contribution of the current element"? I kinda-sorta feels like it must
> be the accumulator, so, plunging onward . . .
>
> "--is performed by an operator function"
>
> Uh-oh: passive voice sentence construction. And "operator function" is
> . . . well, all operators are functions in Haskell, so it's performed
> by an operator, but--
>
> I could go on for a while, but let it suffice to say, long before I'm
> halfway through this sentence, the cognitive load is starting to crush
> me. How many times will I have to read it to understand it? Well, I
> probably won't understand it with multiple readings. Because there I
> see "monoid" toward the end (no hyperlink), and again, that feeling:
> Haskell may be very powerful indeed, but a lot of the writing makes me
> want to kill somebody. (Don't worry. I don't kill people.)
>
> Now, remember what I said about target audiences? I can imagine a
> reader who would actually admire that sentence. But that reader is
> someone who has used foldr and foldr a lot, who has a pretty adequate
> mental model already, and thinks: "Good. It summarizes all my
> knowledge, while refreshing me on a point that hasn't mattered much in
> my coding so far." The sentence may contain a few unnecessary words,
> but for such a reader, these are like drops of water rolling off a
> duck's back. It might read more smoothly with a few added words, but
> this reader is mentally inserting such smoothing linkages in his
> internal conceptual schema, probably without even subvocalizing those
> words.
>
> Still, there might be a way to break it up and with not many added
> words, satisfy more readers. Do you want to do that? Do you need to do
> that? Let me tell you something, either way: it'll probably be harder
> for you than writing the sentence you wrote.
>
> This is an interesting point illustrated in a different field, by Paul
> Krugman, a few years after he started writing about economics for
> layman-reader outlets like Salon: It was actually harder for him to
> write the same number of words for a layman, on a given topic, than it
> was for him to write a journal article to pass peer review. He had to
> think: "What might my readers NOT quite understand yet? How can I get
> them there quickly?"
>
> As an economist, he could think in graphs and equations. And he could
> easily say things like "there could be labor-activism-related
> variations in how downward-sticky wages become in a liquidity trap."
> If he said that to your average economist, he could count on being
> understood. It was actually harder for him to write something more
> generally accessible, like, "When consumers have snapped their purses
> shut in a recession and during the slow recovery, most bosses will
> prefer to lay workers off to cut costs, rather than cut wages to keep
> workers on payroll. However, others may not. It could depend on how
> much that boss fears that the workers would go out on strike in
> response to a pay cut." It was harder for him than for me (I'm not an
> economist) because first he had to realize: if I say it in the way
> that's most obvious to me, most people won't get it.
>
> > are these a step in the right direction, or examples of more writing
> > that sucks?  These are reference documentation, not beginner tutorials,
> > so a more detailed write up of the concepts, pitfalls, ... things to
> > keep in mind when using library, ...
>
> As I say, for a certain kind of reader, that sentence that I only
> stumble around in may be fine for your audience. But Haskell has
> apparently plateaued, after surviving a phase where, as Simon
> Peyton-Jones points out, almost all new languages die. So it's a
> question of what you want to be a part of: a relatively insular
> community? Or a drive to expand the community, by making learning
> easier?
>
> > More of that sort of thing would help me to more quickly learn to use
> > some of the libraries that lack this sort of overview prose, but perhaps
> > what you're looking for is something else?
>
> I've written at very low levels -- e.g.,  very tight assembly code to
> fit into a 512-byte disk boot block on up to very high levels --
> attempts at cognitive-linguistic modeling of spreading activation in
> conceptual networks, in Erlang. My big problem has been finding a
> treatment of Haskell that roots its model of computation in something
> more computationally concrete than, say, lambda calculus or category
> theory. Like I could find for Lisp. Like I could find for Prolog. Like
> I could find for Erlang.
>
> I once tried to get Erlang up on a platform with an old C compiler,
> and got a little obsessive about it: there was a nasty stack crash
> before I even got to the Erlang shell prompt, and I basically had to
> resort to laborious breakpoint debugging to find the problematic line
> of code. On the way down to that line, I passed data structures and C
> code that had me thinking, "So that's how they do that. Well, but, it
> was already pretty obvious. It had to be something like that. But
> guys: clean up your code, OK?"
>
> I have yet to gain any such feeling for Haskell. I once thought I
> could-- I found a very small 'compiler' for Haskell on github, written
> in C, that actually worked for a lot of things. (It could swallow
> Prelude easily.) It was maybe 2000 lines of code. I was encouraged
> that it generated some kind of VM assembly code. Alas, the VM code
> emitted turned out to be for some graph-combinator thingie I didn't
> understand. And I laid the code-study project aside. I thought,
> certainly, somebody somewhere has drawn a not-too-abstract data
> structure diagram that shows how thunks relate to data, and how type
> variables are represented, and how they directly or indirectly link to
> thunks. With that, I could think about the Haskell execution model
> with my eyes wandering around the diagram: this happens here, the next
> thing happens over there, opportunities for parallelism happen on this
> branch, dispatching of tasks happens down inside this thing, and  it
> all comes back here. And that's why my output looks the way it does.
> Mystery solved!
>
> Now, if somebody harumphs and remonstrates, "That's not how you should
> try to understand Haskell!" I'm just going to reply, "Maybe it's not
> how YOU came to YOUR understanding. But look: I'm not you, OK? I'm me.
> I need to understand how a language works from the nuts and bolts on
> up. I won't feel confident enough in it otherwise."
>
> But I'd only say it that way if I was in a mood to be relatively polite.
>
> Regards,
> Michael Turner
> Executive Director
> Project Persephone
> 1-25-33 Takadanobaba
> Shinjuku-ku Tokyo 169-0075
> Mobile: +81 (90) 5203-8682
> turner at projectpersephone.org
>
> Understand - http://www.projectpersephone.org/
> Join - http://www.facebook.com/groups/ProjectPersephone/
> Donate - http://www.patreon.com/ProjectPersephone
> Volunteer - https://github.com/ProjectPersephone
>
> "Love does not consist in gazing at each other, but in looking outward
> together in the same direction." -- Antoine de Saint-Exupéry