Various wording problems

[ugwe43to874nf4]

A number of problems with confusing or dubious words in some of the explanations:

(About currying)

into the same function with an arity of one

This is, very obviously, wrongly worded. It cannot be, in the general case, the same function with an arity of one. Saying that does not really explain at all what it means.

(About composition)

A function which

Composition is an operation, a process... not necessarily a function.

(About purity)

The example shows lack of side effects (which are explained in a later section) but it doesn't show the constrain of depending only on input values.

(About idempotence)

if it has no side-effects on multiple executions

Again, wrongly worded, or at least confusingly worded. It means multiple executions do not change the result further. Exactly what the f( f( f(x) ) ) === f(x) says. Mentioning side-effects in here does not help in any way; it just confuses things.

(About point-free style)

the definition does not explicitly define arguments

To be more precise and avoid repetition of definition-define, it would be better to say it doesn't identify, mention or name the arguments, not that it doesn't define them.

(About Categories)

Objects with associated functions

The use of "Objects" there is potentially very misleading. The same happens later when Functor is defined as "An object with a map function". Generally, a much more clear word there would be types instead of objects. The explanation of Functor seems to go back and forth between insinuating that a particular array is a Functor and saying that Array itself is the Functor. Later still, in Monoid, the reference to types is finally made. But then again Monad, Setoid, Foldable... go back to using "object" instead of "type".

(About lift)

Lift is like map except it can be applied to multiple functors.

This seems to be (sort of) a particular definition of lift, but I wonder just how general this is and I feel it raises confusion with the more general transformation of lifting. Maybe a reference to the Fantasy Land Spec should be made right at the start of the document?

(About Monad)

of is mentioned but neither explained nor shown in examples.

(About Isomorphism)

The definition is anything but clear... "structural in nature and no data is lost" doesn't really help.

[jethrolarson]

PRs welcome

[jethrolarson]

I addressed some of these in this PR #42

[jethrolarson]

I'm interested in exploring how to communicate the distinction between types and objects in a way that is understandable for a jQuery developer.

[ugwe43to874nf4]

Well, it's hard, specially since "jQuery developer" can mean a number of different circumstances and experience :)

I do think that using the word "object" to refer to "type" in this context is going to be confusing. The problem is that there aren't many built-in types in JS, and that a "jQuery developer" might not have a clear view of what type means (they might, but they might not). But even so, I think they will understand it more clearly by using the word type. Maybe, also, more care could be placed into specifying if you're speaking about Array or "an array".

[jethrolarson]

Well maybe we should define type then we can use that more accurately.

On Tue, Jun 7, 2016, 3:52 AM ugwe43to874nf4 notifications@github.com
wrote:

Well, it's hard, specially since "jQuery developer" can mean a number of
different circumstances and experience :)

I do think that using the word "object" to refer to "type" in this context
is going to be confusing. The problem is that there aren't many built-in
types in JS, and that a "jQuery developer" might not have a clear view of
what type means (they might, but they might not). But even so, I think they
will understand it more clearly by using the word type. Maybe, also, more
care could be placed into specifying if you're speaking about Array or
"an array".

—
You are receiving this because you commented.

Reply to this email directly, view it on GitHub
#41 (comment),
or mute the thread
https://github.com/notifications/unsubscribe/AAB-4KYNKg57SN82DfKtgXvDqgbibGKMks5qJU1ngaJpZM4IuxYP
.