Add lens tutorial in Control.Lens.Tutorial

[Gabriella439]

No description provided.

[ekmett]

I have to confess I'm not a big fan of including a "tutorial" module like this.

Documentation, README, wiki, etc. sure.

[ocharles]

You might not be, but your users will be. It does no damage, I think this is a great idea.

[ocharles]

Though it may be worth to put this in Tutorial.Control.Lens or something to really stand out from the hierarchy. Could also have A.Control.Lens.Tutorial to sort it at the top of the Haddocks ;)

[ocharles]

Sorry for the spam, but one suggestion I'd make is that we use @ ... @ blocks if possible, and then we can hyperlink to the actual Control.Lens functions we're using.

[shachaf]

It seems odd to me to privilege this lens tutorial over all the others by putting it in the source code. Why not publish it as a regular article?

[quchen]

The Tutorial module is one of the greatest things of the Pipes library, and it really helped me and many others.

The key differences to publication as a standalone article are:

• Can be updated along with the library. I think this one is very important.
  • I can pick up an old version of Pipes and read the tutorial for that version.
  • Searching for tutorials online usually does not easily yield one that works with the current version very well.
• Officially endorsed by the library authors, so the level of trust in the tutorial is much higher.
• Source linking on Hackage works.

[Gabriella439]

I'll combine @shachaf and @ekmett's questions into the following two paraphrased questions:

Why should we privilege this tutorial?

Reason 1: An "official" tutorial focuses tutorial contributions and reduces the barrier to people contributing new tutorial examples.

Every new tutorial that a person wishes to contribute has a large fixed overhead. The author must first motivate the tutorial, then introduce preliminary concepts before they can discuss the substance of the tutorial, and then the tutorial has to be long enough to justify these large fixed overheads. A centralized tutorial eliminates these overheads so that a person need only contribute their one small example, greatly lowering the barrier to contribution.

A great example of this was this recent pull request contributed to my foldl library just yesterday:

https://github.com/Gabriel439/Haskell-Foldl-Library/pull/38/files

The user contributed a small, but useful, example to the foldl tutorial because the barrier to contribution was so low: there was an existing tutorial skeleton in place that they could slot their example into. Such an example would have been too small to justify its own separate tutorial.

Users are also more inclined to contribute to a tutorial if it is deemed "official" because then they know their effort is not being wasted on some weedy little tutorial that nobody really cares about.

Reason 2: Users also prefer a privileged, trusted, and "official" tutorial

Users prefer official tutorials because (A) they know they are not wasting their time reading it and (B) they feel "certified" to begin using the library after completing the tutorial.

They hate having to piece together information from a large number of fragmented tutorials, especially when each tutorial has the exact same fixed overhead of introduction, motivation, and preliminaries that they must sift through.

Users also never feel like they are "done" reading tutorials because they have no reference point for how much they need to know. The "official" tutorial gives them that reference point for what new users are expected to know.

Why isn't this an article / README / wiki / blog post?

For the same reason that the library's documentation is not in an article / README/ wiki / blog post.

The benefits of embedding documentation in haddocks are that (A) documentation is more discoverable the closer to the code it is (it travels with the code!) and (B) we can use the haddock tool to enrich the tutorial.

There are other ancillary reasons for a tutorial module, many of which @quchen noted:

• It's under version control
• It welcomes outside contributions
• It stays in sync with the library (you get the correct tutorial version for each library version)

... but discoverability and haddock support are far and away the most important reasons for these sorts of modules.

A README comes close but it is not embedded in haddocks like a tutorial module. When you embed tutorials within the haddock documentation you can doctest the examples (which I need to fix by the way), link to types, functions, values, or other modules in the tutorial or code examples (like @ocharles suggested). Moreover, haddock ensures that these links stay up to date with library version bumps.

[ekmett]

If we decide we're going to include it in the code another thought about placement might be to place it in Control.Lens itself.

[fumieval]

👍 on to place the tutorial in Control.Lens. I don't care a tutorial module much, but to include it in Control.Lens sounds more agreeable to me.

[Gabriella439]

Alright, I can move this to Control.Lens

[Gabriella439]

Alright, I fixed the failing doctests and moved the tutorial to Control.Lens

[Gabriella439]

Are there any objections to merging this?

[ekmett]

Are there any objections to merging this?

Sadly, yes.

I've gotten mostly negative feedback from the other folks who contribute to the project on a regular basis on including this as-is. The general consensus is that, yes, we should include a tutorial. There seems to be a general consensus that they don't particularly like this one, however.

It doesn't follow the style or conventions of the rest of the package, and folks have expressed objections that you're asking us to tacitly endorse a lot of words that we don't all tacitly agree with.

I've been leaving this issue open to remind me that we need to do something on this front. I've also deliberately not really said anything on it because I didn't want to create a tempest in a teapot or huge call to action.

[drwebb]

It's a real shame to see a documentation rejection for lens, a package that will one of the first exposures most users will have to the "higher" aspects of Haskell type theory. Especially, after all the hard work that must have gone in to this. Library documentation is a major limiting factor for Haskell, and in my opinion documentation isn't a place to "avoid success at all costs". I hope this at least gets published elsewhere. For important packages like lens, that are a really a learning resource as well as lens library, tutorial modules seem very nice. They will be even a better idea with the hyperlinking source that Hackage is being upgraded with.

[ekmett]

I'd like to be clear. We are decidedly not rejecting the idea of including a tutorial in Control.Lens.

What has happened here is someone effectively put together a large pile of words and said "here, endorse this", and a lot of people who have poured years worth of work into something and have nuanced opinions about how it works and the structure of how to teach it have rejected having this exact string of words shoved in their mouth.

I respect that it probably took a couple of days to write this tutorial.

I also respect the opinions of those I've spent years working with on this project.

I also frankly, don't have a couple of days to do an intensive editing pass and start to build a consensus at precisely this minute. This isn't happening in the next few weeks, between prepping material for fpconf, reviewing submissions for the haskell implementor's workshop and putting together another talk for CUFP I'm fully booked.

So, yes, we'll put a tutorial in Control.Lens and it may draw to a greater or lesser degree from the contents of this tutorial, but it won't be as simple as clicking the Merge button and going about our day.

[Gabriella439]

Then is it alright if I reappropriate this as a lens-tutorial package with a single Control.Lens.Tutorial module? It sounds like you don't plan on using that module name anyway

[bennofs]

You can also write this as shiftAtomX atom = atom { _point = _point atom { _x = _x (_point atom) + 1 } }, so at least the drawback "... the more fields you add ..." is not quite right, because this expression doesn't depend on the number of fields.

[bennofs]

@Gabriel439 Maybe this tutorial is more appropriate for lens-family or microlens?

Perhaps we could even add a note to the lens description linking to microlens or lens-family, since those are much easier if you're starting?

[cblp]

_element = "O"

[ekmett]

@Gabriel439 That sounds more than fine.

[ekmett]

I'm going to close this pull request then.

[ekmett]

@michaelt: I've explained with as much nuance as I possibly can the situation above.

I'm sorry that you seem to chosen to take the worst possible interpretation of my words and run with it.

[tonymorris]

Thanks for keeping the documentation for lens to a high standard. Beginners will appreciate it.

[tonymorris]

I look forward to being better informed by you on the seriousness of my thoughts.

[ekmett]

@michaelt I very much do appreciate the submission, but I think I would rather draw from the tutorial wherever it is placed than commit it en masse and take out a hacksaw.

[ekmett]

Note that these are not the considerations that were actually expressed above, which is the difficulty most of us are having.

The points that I was adding above were in addition to everything that had previously said in the thread -- not in lieu of what came before.

I was asked "is there any objection to merging this" and I replied yes.

To enumerate another reason:

We have a number of things that will likely go out over the course of the next month, that require little or no oversight or effort. 4.13 is pretty much around the corner, as I'd like to get some things like @treeowl's request to move some code up into reflection out of the way, and figure out if we want to proceed with the pattern synonyms that we are currently exploring in HEAD.

These are all things that can largely proceed without much management.

This is not one of those things.

Consequently, it wasn't going to get merged in in the meantime, even if we agreed on 90% of the content, which we don't. We obviously disagree severely on the usefulness of this tutorial as a skeleton from which to build another one.

I personally think it would be as much work to get this one into a form we could accept as it would be to write another one and to draw ideas from this one, and it would be far more acrimonious.

All that has happened since I replied to Gabriel's prod is I've had is a couple of other people fretting and declaiming that the sky is falling because I haven't merged his tutorial. The very days of work that I was deferring by not accepting the burden right now have been shoved back in my face in a much more confrontational way by people effectively demanding that I merge it right now.

The most reasonable voice in the room on the subject is @Gabriel439, who simply and very quietly asked if he could just ship it as another package, which is entirely reasonable and 100% within his purview to do.

I generally don't stress out about much of anything, but frankly right now, I'm going from "hey that sounds like a fun project to do when I get back and have time to breathe" to something I don't even want to think about any more.

Every attempt that I've made to spare folks' feelings on the matter has been thrown back in my face as a reason to drag this conversation on further with no end in sight.

[ekmett]

I'd lock the issue, but despite how cathartic that would feel, frankly I don't want to set the precedent.

[Gabriella439]

I just want to remind everybody that we're all on the same team, even when we disagree strongly. We all want the Haskell language to succeed and become mainstream and we just have different ideas for how to go about that.

[ekmett]

Hear, hear.

[tonymorris]

I ❤ @Gabriel439