more accessible documentation? #178
Comments
|
Let me attempt to address.
Okay.
Belief belongs to a concept called religion.
Okay.
What could be bettered?
The tragedy of the commons. If your co-workers cannot understand your code, then write it so they can. If you cannot do that, the library doesn’t apply to the level of your co-workers. Not everybody understands Haskell either.
Abstract nonsense? Since when was abstract nonsense? Is category theory, for example, nonsense? After all, it’s abstract as f**k.
I agree. You should. It’s good to be an explorer. 42 is not the answer. O, well ...
I had the same feeling about JavaScript.
Okay. What would be relevant?
Fair enough. What should be added?
Keep swimming. Maybe a submarine is a good example? Better yet, what are you looking for?
I once went to a dating site, and ... well, same.
You’re looking for basics?
I belive that could be improved. Likely an article addressing your particular use case. I have to stop here because I am getting tired reading the flood of text that is mostly a complaint about communication not fitting a particular purpose. I’d love to address your concerns later ... maybe after your next post. |
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.
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.
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.
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.
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
I think that's a good suggestion.
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? |
|
@Frikki Although there are apparently several questions in your reply, I don't see anything that looks like it really wants an answer. All of your "what could be better?" "what would be relevant?" "you're looking for basics?" questions are things I did attempt to address in my original post and even in the parts of it that you quoted, and I don't have the sense that I would make anything better by repeating those parts. I hear that you perceive much of my post as complaining and as a wall of text half of which you didn't read. Okay. Regarding whether category theory is "abstract nonsense"... yes. Again, I don't use the term to be dismissive or derogatory; I mean it in the sense well-described in the Background section of the linked wikipedia article, which agrees with how my category theory professor used the term. |
|
@Avaq Thank you! Your reply was incredibly helpful to me, as it clarifies quite a lot of what I was wondering about and was unsure of about creed::async. In fact, as I look it over again, I get the sense that the entire text of your reply, if it were simply dropped into an early part of the README with minor edits, would serve fantastically as exactly the motivational and contextual bridge that I was missing. Yes, I find the Fluture documentation to be quite accessible; things like your links to basics contribute well to that, as do your many comments and cross-links from one concept to related concepts within the doc itself. My sense is that if the creed::async API doc could be filled out a bit with such comments and cross-links, it would become similarly accessible. For one very specific example: in the API section, I'd get benefit from seeing "then" and "chain" cross-reference each other with something like " |
|
@Avaq Just to clarify this particular point...
Sure, I'm not suggesting writing another introduction to common introductory material that exists elsewhere-- I agree that links to such (with an appropriate amount of explanation of why they are being linked and how they relate to the current material), serve quite well for that. When I said "from first principles" (probably a poor choice of words), I meant specifically "without depending on Promises/A+ documentation". Promises/A+ serves a necessary purpose at the moment, but, in an ideal future, Promises/A+ will be forgotten and more tenable projects like this one will live on, so it would be good to avoid dependencies on Promises/A+ docs (other than perhaps for historical context-- not for concepts). |
In fact, Promise is not even a Functor.
Fantasy-land is not an alternative, it is not even a library. It is more of a collection of densely written and opinionated specs aimed at library writers. It does assume familiarity with many concepts it mentions and does not aim to provide any introduction nor give examples. For something more accessible, in addition to the excellent "Professor Frisby's Mostly Adequate Guide to Functional Programming" mentioned by @Avaq, have a look at the practical examples in https://github.com/dmitriz/functional-examples.
It is true that adding some more explanations to this example would not hurt.
It does show some good features to get started, as well as the friendly REPL inspector facility. > all([1, 2, 3].map(resolve))
Promise { fulfilled: 1,2,3 }and perhaps not "too introductory" as it simultaneously uses 2 new operators. > creedPromise = resolve('hello')
Promise { fulfilled: hello }
> creedPromise1 = creedPromise.map(str => str + '?')
Promise { pending }
> creedPromise1
Promise { fulfilled: hello? }
> wrappedPromise = creedPromise.map(resolve)
Promise { pending }
> wrappedPromise
Promise { fulfilled: [object Promise { fulfilled: hello }] }
> together = all([creedPromise, creedPromise1])
Promise { fulfilled: hello,hello? }
// WAT? Ok, that one was a bit cryptic, so let's test it ...
> together.map(console.log)
Promise { pending }
> [ 'hello', 'hello?' ]So we see that > native = Promise.all([creedPromise, creedPromise1])
Promise {
... (mostly useless information from the native promise inspector)
> native.map(console.log)
TypeError: native.map is not a function
> native.then(console.log)
...
> [ 'hello', 'hello?' ]
Indeed, this surely is an advanced one, outside the core methods, not clear why it comes first...
That one is actually more basic, demonstrating how to turn a method from NodeApi into a creed promise: > let {fromNode} = require('creed')
undefined
> readFileToCreedPromise = fromNode(fs.readFile)
[Function: promisified]
> readFileToCreedPromise('someFile', 'utf8')
Promise { pending }
> Error: ENOENT: no such file or directory, open 'someFile'
It is true that an "Introduction" section aimed at "ordinary promise users" is missing.
These are excellent suggestions. An introductory section "Why would I use creed?" for regular promise users would certainly lower the access bar. Maybe start with some scary "then-able" surprises and move on showing how things are more transparent and easier to reason about with the sane |
This. 💯 |
I would not recommend to start a tutorial with that. New users want to learn how to use the Creed library, not hear our opinions about why |
|
Hi everyone. Thanks for the discussion. I'm sorry I've not been able to respond until the weekend (my time lately is very limited during the week) I think there are some very good suggestions in here, and I'd like to try to focus subsequent discussion around those. Hopefully we can get to some tangible goals and start to turn them into concrete doc improvements. Here are the things I saw mentioned that seem like they would be helpful improvements:
I like all of these ideas, and I'm open to doing them. If creed moves forward with these, I'd love help. As I mentioned, my time has been very limited over the past few weeks, and that's likely to continue for at least another 1-2 weeks. Discussion is helpful, and of course PRs would also be helpful. |
I actually would find it helpful. My first questions, when seeing a new library, are not "How to use it?" but "Why use it?", "What it brings to the table?" and "What it does that X and Y don't do? In this particular case, we have a library seemingly similar to the native Concerning Without knowing that other side of equation, native promises look wonderfully easy to use and "working just fine" and "being used by everyone without problems", so why making life harder by "pleasing some few category theory sadists" 😄 I have not made it up, that is really what I've seen written even by experienced programmers. To which I can't think of any better response than by @tjaskula in his highly educational Medium article Can programming be liberated from the von Neumann style?:
I understand it has some deeper roots in certain unfortunate education culture, that we obviously can't fix here. What we can do though, is explain how and where that knowledge can be practically beneficial in the specific use cases that As for well-motivated opinions by people with experience, these are actually quite helpful to newcomers and great way to learn quickly and save a lot of time. As any other library, this one is based on certain opinions of the people who designed it, and knowing and understanding those is actually incredibly helpful, specifically when using the library. |
|
In addition to these:
|
In this direction, it would be good to have some very basic but realistic examples. I will look into rewriting the Any PR to |
|
@dmitriz Thank you for putting together those examples! I think the next step for this particular issue is actually to create a new issue that represents the concrete work to be done--from here and here, and potentially drawing from (and/or linking to) @dmitriz's examples. Once again, thank you, everyone for the discussion and suggestions. |
|
See #179 |
|
It turns out I was swamped for more than the 1-2 weeks I originally thought, but I just started working on the items in #179. |
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.
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:
async-problemexample. 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.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:
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.
The text was updated successfully, but these errors were encountered: