Change the tone of the documentation

[sjshuck]

This is an excellent and principled library that demonstrates Haskell's ability to be transparent in implementation, so when you call a function, you know what it's doing.

However, the docs' tone is frankly horrible. It's cringeworthy to read and has been a real turn-off to adoption for me. Here is one example of many, many within:

But in fact, the standard alarmist talk about retraversing binds and quadratic explosions and costly appends, and so on become transparent nonsense with Stream f m r in its streaming use.

This is a rewrite of that sentence:

Many commonly cited performance issues (retraversing binds, quadratic explosions, costly appends etc.) do not apply to Stream f m r in its streaming use.

We have the same content but we're not condescending swaths of the community. In either case, the discerning will isolate the content and draw their own conclusions; the only thing I can imagine that's added by the snark is incidental interest in the library motivated by dubious "emotional" factors.

I would be happy to contribute a large edit. Here's a sample of my docs style for reference. (I won't put work into it unless it's deemed appropriate by the maintainers.)

Thanks!

[treeowl]

Good gosh, yes. Please.

…

On Wed, Dec 23, 2020, 7:31 AM Shlomo Shuck ***@***.***> wrote: This is an excellent and principled library that demonstrates Haskell's ability to be transparent in implementation, so when you call a function, you know what it's doing. However, the docs' tone is frankly horrible. It's cringeworthy to read and has been a real turn-off to adoption for me. Here is one example of many, many within: But in fact, the standard alarmist talk about *retraversing binds* and *quadratic explosions* and *costly appends*, and so on become transparent nonsense with Stream f m r in its streaming use. This is a rewrite of that sentence: Many commonly cited performance issues (retraversing binds, quadratic explosions, costly appends etc.) do not apply to Stream f m r in its streaming use. We have the same content but we're not condescending swaths of the community. In either case, the discerning will isolate the content and draw their own conclusions; the only thing I can imagine that's added by the snark is incidental interest in the library motivated by dubious "emotional" factors. I would be happy to contribute a large edit. Here's <https://hackage.haskell.org/package/pcre2-1.1.0/docs/Text-Regex-Pcre2.html> a sample of my docs style for reference. (I won't put work into it unless it's deemed appropriate by the maintainers.) Thanks! — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#106>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAOOF7LJXXVWQS2ZCTXJXITSWHPINANCNFSM4VG54SGA> .

[Profpatsch]

I had the same the same when I evaluated the readme, it makes understanding the library a lot harder when your brain has to first parse the writing style in order to get to the technical contents.

[mauke]

1. I fully agree. I don't want to read about "the hermaphroditic chimera" that we "find in our diseased base libraries" when I'm just trying to figure out how to use this library. Less unhinged ranting, more practical advice, please.
2. In the case quoted above, it is not just the tone that is bad, but also the content: Stream does have quadratic performance; see issue Quadratic performance on left-associated binds #109.