more accessible documentation?

I have trouble taking native/A+ promises seriously, mostly due to its impossible-to-analyze behavior around automagically unwrapping thenables (I believe this is commonly known as “failure to be a monad”).

As I consider long-term solutions, alternatives like fantasy-land and creed::async become quite attractive. But, frustratingly, my several attempts to dive into either one of them have failed, due to my failure to being able to follow the documentation of either, to any significant depth. I also have the feeling that, even if I succeed in vaulting the very high bar to entry, I will leave my normal friends and coworkers behind, since they will be unable to ever read my code from then on.

• The fantasy-land doc dives straight into algebraic “abstract nonsense” (I don’t neceessarily use the term dismissively, but it does make that doc impenetrable and thus not useful to me for learning).
• fluture-js/Fluture might be a decent alternative; I’ll explore that in parallel.

This creed::async certainly sounds great, from its introductory blurb (great marketing!), so I’d really like to try it, so that’s what brings me here.

As I continue reading the README, I encounter:

• The async-problem example. Ok, I guess it solves this puzzle neatly. Can’t really make head nor tail of the details at this point, and it’s doesn’t seem that relevant to my wish to learn the library.
• The “Try it” section. Ok, I follow this section: it looks just like the Promises I know, so far, but there’s not a lot in this section.
• … scrolling down, hoping to see some more introductory examples of how to use various features, and I reach:
• API : Run async tasks: coroutine :: Generator -> (…* --> Promise e a) : Create an async coroutine from a promise-yielding generator. [… example that doesn’t seem relevant to me yet …] WHOA! I suddenly feel very far out of my depth…
• fromNode :: NodeApi e a --> (…* --> Promise e a) [… more stuff that doesn’t seem relevant to me at all …]
• scrolling down more, I see lots more API reference and code examples, but they all seem to assume I already know what’s going on. I’m lacking any context or feeling like I know how to get my foot in the door.

What I’m trying to say is… is there any chance of getting some introductory material in there, to bridge the large gap between the shallow “Try It” section and the deep “API” section, for programmers like me who want to learn this library?

In particular, I’d be interested in some dedicated material explaining, in both plain language and code:

• A list of each the async constructs/styles that creed::async provides, with high-level description of pros and cons of each compared to each other.
• Compare/contrast these constructs/styles with native/A+ promises and native async/await, point out the differences / added-value that are the reason a reasonable person would want to use this library.
• Maybe also compare/contrast with other alternative libraries like Fluture? I actually don’t know how you view creed::async in relation to other alternatives at this point, and it would be good to know.
• Then ease into more depth, with some well-motivated examples of each construct/style without assumption of prior knowledge, with explanations and code comments less terse than the API examples.
• My impression, from reading your and others’ comments in other discussion threads that lead here, is that a crucial motivating point about this library is something like “creed::async::Promise is A+ compliant since it has a compliant then, but if you want something with analyzable semantics, don’t use that, use its ‘chain’ instead”. But I don’t see that stated or even alluded to anywhere in the creed::async doc! (And, truthfully, I’m not even sure I have it straight.) I feel like there may be a lot of other important context and motivation like this that I’m missing, too. A dedicated “Motivation” section might go a long way.

A final note-- personally, I know Promises/A+ already, so I don’t mind if the doc assumes that knowledge, for my own use in learning the library. However, if this library is intended to be a serious option for the world for doing async, it would be great if there were also an introduction from first principles for javascript programmers, so that people can skip A+ and get right to the sane stuff. That would be a more ambitious undertaking, though.

[Avaq]

the flood of text that is mostly a complaint about communication not fitting a particular purpose

I don’t think @donhatch is complaining, I think they are raising valid concerns about the accessibility of the alternative Promise libraries. You might be too hard on them in your response, @Frikki. I think most of what @donhatch said stems from confusion.

I have trouble taking native/A+ promises seriously, mostly due to its impossible-to-analyze behavior around automagically unwrapping thenables (I believe this is commonly known as “failure to be a monad”).

This is exactly the kind of complaint that we would expect from the target audience of alternative Promise libraries. Using Creed, Fluture, Folktale, or similar is indeed a way to avoid having to deal with the absurdity of the native Promise implementation.

As I consider long-term solutions, alternatives like fantasy-land and creed::async become quite attractive.

This seems to highlight the first points of confusion: that Fantasy Land is an alternative to native Promise/A+ somehow.

You don’t need to look at Fantasy Land if you want an alternative to Promises/A+. Fantasy Land only exists to acknowledge within the JS community that some constructs can be related to category theory, and made to interoperate because of that. Fantasy Land describes the association with category theory (hence the abstract nonsense) and an interface for independent libraries to be able to use each others algebraic operations.

As I continue reading the README, I encounter [a lot of in-depth material] What I’m trying to say is… is there any chance of getting some introductory material in there, to bridge the large gap between the shallow “Try It” section and the deep “API” section, for programmers like me who want to learn this library?

The problem you’re running into is that a lot of these documentations assume understanding of underlying concepts. These concepts are broad, and too much for every individual library to cover, but they can also be very widely applied. A great place to start is the Mostly Adequate Guide. Many of the concepts covered there can be extrapolated to understand the documentations of functionally minded libraries.

My impression […] is that a crucial motivating point about this library is something like […] “it has a [Promises/A+] compliant then, but if you want something with analyzable semantics, don’t use that, use its chain instead”

That’s right. Promises/A+ is another spec drafted with interoperability in mind, and for the benefit of interoperability, the people who drafted the spec arbitrarily decided upon these strange assimilation semantics you’ve mentioned before. In order for Promises to interoperate, the then function must behave strangely. The Native Promise implementation (and Bluebird, and most others) took it one step further though, and added the same behaviour to all Promise functions (including all of its constructors), making it so there is no escape from the strange semantics. Creed is different in that it has the minimum necessary to be spec compliant, but it also has sane alternatives to the then function. You as a user are encouraged to use the sane alternatives (like map and chain) and leave then as a means for interoperability and colleagues not willing to make the leap. As an added benefit, map and chain and friends are compliant with the Fantasy Land spec, meaning that interoperability with libraries such as Ramda is also supported.

A dedicated “Motivation” section might go a long way.

I think that’s a good suggestion.

if this library is intended to be a serious option for the world for doing async, it would be great if there were also an introduction from first principles for javascript programmers

I see where you are coming from, but as I mentioned, the underlying principles are shared between all functionally minded libraries and are a lot to cover. Once you are familiar with the basics I assure you all of these documentations will make a lot more sense! In the Fluture documentation, I try to link to material on the basics whenever necessary. It’s my best idea for guiding new users. Perhaps Creed can do the same. How do you think it can be improved?

[briancavalier]

In addition to these:

• it seems helpful for the API docs to emphasize map, et al. and group A+ / ES interop functions (i.e. then, catch, and finally) together and explain more clearly that’s their purpose.