Rewrite documentation to help new users

[ochrons]

Current documentation is more like a technical description of differences to Haskell IO and Scalaz Task and is therefore not very useful for developers who just want to use cats-effect IO without previous experience with Scalaz/Haskell.

The documentation should cover the "why you should use IO" and offer practical examples for incorporating IO into applications.

Bare minimum improvement would be to give a prominent link to this blog post describing IO in cats-effect :) https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html

[alexandru]

👍 but I think we need that article on https://typelevel.org/cats and link to it from the README.

[djspiewak]

I agree with all of this. My general preference for documentation is to have a doc/ directory (containing markdown) in the project root, so things remain versioned with the project. Doing something more elaborate with tut is also completely reasonable. @ochrons Would you be interested in playing around with getting started on this?

[alexandru]

@ochrons we have a documentation website now, at: https://typelevel.org/cats-effect/

Here's the IO document: https://typelevel.org/cats-effect/datatypes/io.html

Is this what you wanted? Can we close this issue?

[ochrons]

Yeah, looking good now. Thanks for the documentation effort!