Enhanced documentation / Playground

[buildreactive]

It would be fantastic to have improved documentation, probably some more introductory information for the non-functionalist, and possibly a Playground. (Sound familiar?)

Approaching Swiftz from a purely Swift (/ Objective C) background, a lot of this will seem pretty incomprehensible. Approaching it from a Scala background makes it much easier, but there are significant syntax differences and features that we just don't see (much) in Scala. For instance, I still have no idea what a Lens is (I really ought to look into that...)

[CodaFi]

I think the first half is a fantastic idea, but I worry about the second. This library involves a lot of concepts that I firmly believe need thorough and (sometimes) rigorous introduction before they can be properly grokked, even by beginners. The concepts in this library have almost no Objective-C equivalents that would make any sense to somebody coming from that side of the aisle, and shimming in a bunch of metaphors to make it so is something I can very much promise will be vetoed by me immediately. Just as Haskell is a complete inversion of belief for these kinds of people, Swiftz and whatever the hell "Practical Swift" are sit at different ends of the spectrum for them. tl;dr I don't want this library to turn into another LYAH because there are much better places you can get that stuff.

That said, and please don't take the above as an anti-novice rant, the docs suck compared to things like Apple's own stuff. I'd like to have an editing spree for the next couple releases before we try to aggregate things together into a nice playground. That way we get a feel for how hard it is to explain each thing in the small before we try it in the large.

[CodaFi]

Perhaps you could help by being more specific about which structures you would like to see more documentation for?