Readme separate to specification

I’ve received a lot of feedback from devs while working on getting Mithril, Lodash and Rx to support Fantasy Land regarding the heady language used in the specification. It is intimidating and creates the impression that it won’t be helpful in their work.

I personally think using precise language in a specification is exactly the right thing to do. But I do think it would be beneficial to explain what the library is, what the benefits are, who is using it, how to get started implementing it, related projects etc on the front page.

I’ve received a lot of feedback from non functional programmers saying a blog post I wrote really helped them see the value, and they then went on to implementing FL in their own libraries, joining the gitter etc. I think this is great! I believe we can get really far if we build a nice smooth on-ramp.

So I’m proposing a separate readme.md and spec.md. The current readme would become the spec, and the new readme would be a document extolling the virtues of fantasy land, etc etc.

The readme would be more colloquial (but still as precise as possible) and focus more on “how” / “why” than “what”.

How does that sound?

For anyone interested, here is a few recent examples, but I’ve got this sort of feedback many many times:

Source

Source

Source

[keithamus]

Hi all! As an outsider here, but keen on the entire FL prospect, I’d be very much interested in picking this up. Shall I just throw together a PR open for criticism? Should some more solid requirements be defined?

[davidchambers]

Good point, @bergus. We could preserve the headings at the bottom of the document to provide links to the new locations. For example:

Functor

See spec.md#functor.

map method

See spec.md#map-method.