search

snoyberg / classy-prelude

A typeclass-based Prelude.
108 stars 15 forks source link

README is too negative #84

Closed rehno-lindeque closed 9 years ago

rehno-lindeque commented 9 years ago

The README for the classy-prelude seems too argumentative to me. While I think it's very worthwhile to list / discuss the arguments against a particular library, in the interest of academic honesty, I think it's the README's job to promote the utility of the library for people taking a first glance at it. I feel that too much of an argumentative tone here seems needlessly defensive and will erode the initial impression of the library (I couldn't say where exactly, but I've noticed this elsewhere in the yesod platform too). Since moving over to classy-prelude I've personally found it very helpful for simplifying our application-level code and I'll continue to use it (or adapt it) until a suitable alternative arrives (backpack perhaps!?)

That is to say, everything currently in the README actually seems fine to me, it's only that I'd delegate a discussion of the trade offs to a section near the end with some additional practical advice on how to use. For example, a warning against using in generic libraries is warranted I'd say. I'd also like to see a quick overview comparing classy-prelude to other preludes in order to help me make a more informed choice when diving in for the first time - I'm too busy to read long articles unless I'm really trying to learn something :)

snoyberg commented 9 years ago

I have no objection to such changes; I haven't actually looked at the README since I wrote it (which apparently is about 2 years ago). Would you like to take a stab at updating it?

snoyberg commented 9 years ago

By the way, I agree that I've had too defensive a tone in a number of articles in the past. If you see other examples, please do point them out, I'd like to work towards correcting that.

rehno-lindeque commented 9 years ago

Awesome sauce, ok I will take a stab at it - we're a little busy at the moment but documentation should be pretty easy to contribute so I'll try to do some here.

gregwebs commented 9 years ago

I had updated the mono-traversable README but never classy-prelude. I deleted the entire existing README in 97f023571c0f3b5a289e4f04db8a50e21fc66be5 and pointed to updated information

@rehno-lindeque let me know if this is better. We should pull some information out from the blog posts at some point and put them in the README and only use blog posts as an appendix.

rehno-lindeque commented 9 years ago

That would work well, I think a list of links is a good intermediate step before pulling stuff from blog posts. The first reference sounds like a good what & why and the second seems like good practical wisdom (when & how). Also seems more up to date with the reference to mono-traversable, so +1 from me.

gregwebs commented 9 years ago

closing this because "negativity" is solved. we can still improve the README though.