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

[Michael Turner]

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