search

fantasyland / fantasy-land

Specification for interoperability of common algebraic structures in JavaScript
MIT License
10.12k stars 376 forks source link

Readme separate to specification #177

Open JAForbes opened 8 years ago

JAForbes commented 8 years ago

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:

image

Source

image

Source

image

Source

davidchambers commented 8 years ago

Excellent idea, James. I agree that the readme should explain why a specification for interoperability of common algebraic structures in JavaScript is important. I appreciate the simplicity of your proposed solution.

rpominov commented 8 years ago

Yea, it seems like currently the way this repo is organized is targeting people with Haskell background coming to JS who want to do Haskell stuff in JS. And I think we should make it more approachable for people coming from JS background and just wanting to do FP in JS.

I think this talk https://www.youtube.com/watch?v=oYk8CKH7OhE by author of Elm is very related here.

JAForbes commented 8 years ago

@rpominov I nearly linked to that exact talk! :D

bergus commented 8 years ago

So I'm proposing a separate readme.md and spec.md. The current readme would become the spec […]

Don't forget that this will break quite a share of links that refer to individual types. I don't have a better suggestion though.

davidchambers commented 8 years ago

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.

rjmk commented 8 years ago

If we do this, could the first sentence be something like Fantasy Land is **[a specification](spec.md)** for common algebraic structures in JavaScript. The actual first sentence is not so much my concern, but a prominent link to the spec very early on seems important to me.

Perhaps a Usage section would work equally well. Either way, I think we need to make clear that the bit you need is the spec.md, and that the README is just for explaining why you need it

SimonRichardson commented 8 years ago

I have no objections in completely changing to more than one markdown, I think the spec has grown enough now.

dead-claudia commented 8 years ago

I also agree it'd be nice to have a separate specification document. From an implementor's perspective, both the normal prose and spec have grown enough that it's slightly difficult to navigate.

Also, I feel moving the spec out of the README would give room to explain the API in less technical terms, to be more approachable for people less familiar with functional programming.

safareli commented 8 years ago

Also if we move actual spec in separate file we could leave image in README and it will fix issues discussed in #118. We could also have the image in spec.md but in the end of file for the same jump issue.

safareli commented 8 years ago

also it would be nice to have contributing.md too

joneshf commented 8 years ago

It sounds like everyone is in agreement. Who wants to take the first step here?

I am going to bow out for the first pass because I feel like my influence on tone would be more on "what" than is appropriate here. I'll gladly provide feedback though.

keithamus commented 8 years ago

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?

joneshf commented 8 years ago

That would be wonderful!

ccorcos commented 7 years ago

When looking for examples, @DrBoolean did a great job explaining some real world use cases in his egghead series

kwijibo commented 7 years ago

Don't forget that this will break quite a share of links that refer to individual types. I don't have a better suggestion though.

Another option could be to keep the readme and links intact, but create a user facing github-pages site, which could publish a user-friendly intro, examples, spec, implementations list etc.

The disadvantage is that this would be more work, and making changes would probably involve a build step.

dead-claudia commented 7 years ago

@kwijibo There's always GitHub Pages + Jekyll, if a build step is necessary.

Raiondesu commented 4 years ago

Hey, uhm, what's the status of this?

It's been three years now, and the idea is superb. So what's next? FL still doesn't have a proper way to welcome newcomers like me...

beck commented 3 years ago

@JAForbes thank you tons. Came here from an old RxJS ticket. Your comments, which have both deep empathy and technical knowledge, are still paying dividends.