Tutorial is hostile to novices

In multiple places throughout calmmjs and lenses’ Readme it says: “If you’re new to lenses, read the partial.lens tutorial/docs”.

However, the tutorial is extremely hostile to novices:

Let’s work with the following sample JSON object:

Ok

First we import libraries

Ok

and compose a parameterized lens for accessing texts:

What?

• What do you mean by compose? (I know what it means in functional programming. Lens is a new concept to me, are we on the same page?)
• What is a parametrized lens? (how does it differ from regular lens? partial lens? what is a lens?)

Take a moment to read through the above definition line by line.

I would if I:

• could understand what each line does
• could understand what the end result is going to do

The purpose of the L.prop(…) parts is probably obvious.

No, it’s not

Then the tutorial goes on to querying the data, dealing with missing data, etc.

Exercises

Take out one (or more) L.define(...), L.normalize(...), L.valueOr(...) or L.removable(...) part(s) from the lens composition and try to predict what happens when you rerun the examples with the modified lens composition. Verify your reasoning by actually rerunning the examples.

The “tutorial” basically assumes that the novice:

• is already intimately familiar with lenses
• is already intimately familiar with what L.define etc. do
• and really isn’t a tutorial but a “here’s how one uses partial.lenses”

The tutorial should be split into:

1: explaining what lens are and how they can be used? The explanation should not rely on reference. Current description goes like this:

Lenses are basically a bidirectional<link to API reference> composable<link to API reference> abstraction for updating<link to API reference> selected<link to API reference> elements of immutable data structures

Which is gibberish to a novice.

2: step by step example building of the final textIn lens explaining each step and what it does

3: more advanced examples, shorthands, multiple values, decomposition etc.

[polytypic]

It would also be awesome if you incorporated your response into the tutorial 😃

Working on it…

[polytypic]

Thanks for the feedback!

Unfortunately I’m not a novice. I’ve been programming roughly daily since about 1990 and I started to get into functional programming in 2001 by writing a simple compiler for a simple ML style language in OCaml. So, it is not always easy for me to see where novices may have problems. For example, I recently realized that the term isomorphism is not generally familiar to programmers, so nowadays when I mention the term I tend to explain it in more detail. I assure you, however, that the intention is not be hostile to novices.

What do you mean by compose? (I know what it means in functional programming. Lens is a new concept to me, are we on the same page?)

Yes, composing lenses can be like composing functions. There are multiple ways to define lenses and optics in general. In this library optics are a kind of lifted functions that return computations.

What is a parametrized lens? (how does it differ from regular lens? partial lens? what is a lens?)

A function that returns a lens. Lenses are a kind of DSL embedded into JavaScript for defining data querying and manipulation functions. Embedded DSLs inherit the mechanisms of the host language. To create parameterized expressions in JavaScript one uses functions.

A total function is one that always gives a defined result for every possible input (value in the domain of the function). A partial function is one that may not always give a defined result for all inputs. Consider a function to return the first element of an array. Such a function cannot be total unless the input is restricted to arrays that have at least one element. In partial lenses the idea is that in case the input does not match the domain of the operation, then the input is treated as being undefined.

Take a moment to read through the above definition line by line.

I would if I:

• could understand what each line does

Note that the idea with the suggestion is not that the reader would understand everything, but to encourage the reader to spend a moment to look at the definition so that it is easier to understand the references in later sections.

• could understand what the end result is going to do

The goal is to compose a lens to access texts.

No, it’s not

Check.

The tutorial should be […]

Writing documentation takes a lot of time. If you have specific ideas of how the documentation should be like then please take the time to make it so. PRs are welcome and people can also provide documentation, such as blog posts, outside of the library per se.

2: step by step example building of the final textIn lens explaining each step and what it does 3: more advanced examples, shorthands, multiple values, decomposition etc.

Yes, although more is not always better and my time is limited. But again, I welcome people to both contribute documentation (PRs) and write documentation outside of the library per se (and PR to link to such documentation).