I am making this statement in a purely, purely, completely selfish manner, but I recently picked up Q.js to try and adopt it into my code. My understanding of promises, $.Deferred, the whole async world is - and practically still is, 0.

Now I am not trying to say that I should have documentation catered to me, I'm an idiot in regards to this tech, but this library seems like it is filling a very important role in the javascript coder's toolbox. I think I would have found it a lot easier to dive into if there were some more simple, end to end, copy-paste examples that show Q functioning in less complicated scenarios.

To cite an example, you start off your tutorial with something that already lost me; https://github.com/kriskowal/q#tutorial, you will notice the code begins like this..

promiseMeSomething()
     .then(function (value) {
   }, function (reason) {
});

Okay, right away, you lost me - because I see you having a function here that gets a then chained to it, and I have no clue why. Where did this promiseMeSomething() come from? When does it get a .then() chained function? I'm digesting what I just saw up ahead and I'm already lost here. This trend keeps going as I keep reading.

Am I the average user? I'm not certain, I am certainly not adept with the entire idea of promises and deferrables, but isn't that the people you need to be using Q the most? People like me that want to be better coders, but are reaching out to take hold of the tool boxes available?

Your tutorials then continue on, as I am still lost from the first one. You go through a ton of useful topics, and I will not deny they are awesome. I found the section on sequences to be of specific, particular use. I loved it. In fact I found it so good that it solved one of my problems, it answered a big problem I was having at the time.

But it isn't until halfway through the documentation that we're met with this part; https://github.com/kriskowal/q#the-beginning

It is more than halfway down the docs that we're even shown an example of how to get a promise from something. And even then, it's a bit confusing.

Don't get me wrong, I have no right to criticize, I have no right to complain, and I certainly don't have the intellect to back up a promotion for better documentation. But as a medium-level coder, as someone who came to Q completely unsure of why I needed it, having been told to look into it by a peer, I found it very hard to just get a first sample up and running.

Your library is brilliant, gorgeous even. Now that I have accomplished something with it, I am in love, I want to learn more. I crave learning more. I am perusing the source code like I would a comic book. I understand less than 2% of it but it is so immaculate that I am excited at the 2% I do understand.

But I think that, if you're still going forward with the 2.0 release, you would really reach a lot more people more quickly if there were some much simpler examples that were very rapidly there, in your face, ready to go, that looked like they belonged in the real world.

What hooked me on jQuery wasn't it's documentation, but it's immediate presentation of how it solved a problem I've personally had.

If you go, right now, to jquery.com, this is what you see.

jQuery Front Page

I am immediately shown a real world example, something I've tried to do in the past. Something I need to do right now. It's simple, it's brief, it required me to understand nothing but the fact that I wanted to change the text of a button.

Inversely, if you go to http://documentup.com/kriskowal/q/, right away you see this;

q.js landing page

Wait, now what? So am I getting a Version 1, or a different one? I get the step1() step2() etc example, but then I look at Q.fcall - what is promisedStep1?

This trend is a bit nebulous throughout the Q documentation. There are actually very few places where I found code I could literally copy over to a sample program and just run, to see what it did.

Feel completely free to dismiss this as the ramblings of a stupid programmer, I get it - you are but one man writing a library being used by millions. I just love your library, and in the 3 days I have been using it, I love it so much that I felt compelled to share my experience on how I think it could be more accessible.

I also want to add, if this is an inappropriate place to be putting a comment or statement like this, please let me know. I'm new to using github with other people. I'm new to a lot of this. It seemed like the right place to put things I wanted people who were working on the project to see. If it is not the appropriate place, I'd like to know what a more appropriate venue is.

Thank you for the really thoughtful critique. We should definitely take it to heart.

Q is a bit of a special case because a large part of its target audience is people who know about promises in some fashion already, or at least have been told that promises are a solution to their callback woes. But I think there is a definite potential for shifting toward beginners.

I’ve always considered the audience beginners, but have equally always struggled to reach out to them. Perhaps more specifically, the audience of the Q readme has been shifting over the years, from reaching out to like minded people I needed to help support and promote, to skeptics who might already know the alternatives well enough to judge, and that is perhaps as far as we have gotten. The audience is moving and we may be overdue for a another iteration of the introduction.

I am not knowledgeable enough on everything Q does to comment to a great degree on what you should do. I can only tell you what my own personal experience was like. It's overwhelming, and it was pretty difficult to get into, but certainly not bad in any sense.

I think the most disconnecting part of it all was being so confused about how to get a promise and then how that promise had anything to do with my existing code. That's where I got stuck the most.

To cite an example, my exact problem was that I needed things to run in a specific order. I am using ASP.NET MVC with a _Layout.cshtml and then each individual View has a scripts section. So what was happening was ...

Layout.cshtml Javascript runs
[view].cshtml Javascript runs

This was presenting a real challenge though, because I needed things to occur after the individual view, but still be on the _Layout. I had a huge problem overcoming this and tried all kinds of stupid, fanciful methods of delaying methods, I tried a library called jsdeferred and it kind of helped.

I was directed to Q as a solution to this, because it supposedly had the ability to, and I quote "turn blocks of code into something that promises to be a block of code, but isn't yet a block of code. It actually delays running that code until you're ready for it, but you still have to find a way to be aware of it." (exact statement from a friend of mine)

I had no idea what promises were, or what deferrable was, to be honest. I just knew that I wanted these functions to run in the order I wanted them, and not sooner, and not later. Using Q, I finally managed to accomplish that. And I am super excited about it. It makes my code cleaner to read. It makes it easier to maintain. It means I'm not having to come up with clever tricks to delay things until later, it means I'm not having to try and 'fool' Visual Studio's intellisense support.

I don't know what your audience is, but I do know what your product is - and the answer is awesome. I mean, I'm not even using it right, and the performance of my pages is increasing. I can't even imagine how much better it'll be once I grasp what the hell I am doing and use it to its real potential.

By the way, if you want to see what I ended up doing, you can see it here on my Stackoverflow Post post.

I may be using the library totally wrong, in fact I am almost certain that I am. But it solved a problem for me, and that is what mattered at the end of the day. I'm really looking forward to how I can use Q in other places in my code correctly in order to boost performance and make it function the way I want.

@domenic I have plenty of experience with using promises and the patterns as implemented by popular 3rd party libraries and I still found the documentation challenging.

The problem I personally had was "The Beginning

Everything above assumes you get a promise from somewhere else. This is the common case. Every once in a while, you will need to create a promise from scratch."

We need to set the frame at the top. "Everything above assumes ..." needs to go BEFORE we process the information, so we can encode it correctly. Otherwise it is confusing. :-)

Ah, I want to be extremely, unquestionably clear here that my intention was in no way a jab at the writers of this plugin. Reading over it this morning, I am a bit ashamed at myself as I realize that, if read in the wrong context, the post I made could sound horribly condescending and snide, almost self entitled. That was absolutely never my intention.

I follow up to what @zackster said, I found it challenging to get involved. Even the working solution I amalgamated, while it works and does I want it to do, it isn't using the library for its actual intended purpose. (I would also love any weighing in on opinions of what I did with it. Is the way I used it so bad that I should scrap it and try a new approach? Or is it fine to use it that way? You can see how I used it here in my Stackoverflow Question)

I am a technical writer, and a programmer. It is my experience that most programmers have 2 out of 5 typical skill sets needed (thus why teams work so well). These 5 skill sets, as I have determined in the last 20 years, are as follows;

Programmer (actual coding)
Technical Writer (documentation)
Analyst (reviews behavior and reports on it)
Tester (thoroughly capable of performing rigorous breaking of things made)
Theorist (comes up with the general ideas of what needs to happen, and why)

In the past 20 years of experience I have had, I find that most (not all) developers have at least 2 of these as a strength, and at least 1 of them as a weakness.

I am extremely good at writing documentation, so I may take the time to sit down and try to learn Q inside and out, and try to contribute to its documentation. Though my knowledge and time may not allow for it.

I honestly think the best place for you to start, though, would be simple. If I were looking for a library like Q, and I did not already understand how to use it, then this is what is going through my head.

I have code that is running at the wrong time. I need to fix that. I have code that needs to wait on something else. How do I do that? I have code that needs to run at the same time as other code, but finish earlier. I have no idea what I'm doing

I guide you to exhibit A Caterpie Can't Hack It

In all seriousness, though, here's what I would suggest.

First, and foremost, I think it would be helpful if you put a dist folder on the github that has the fully compiled, fully ready q.js file that any average joe can copy/paste into their stuff. One of the first entry barriers was just getting Q.js. I found that the file at https://github.com/kriskowal/q/blob/v1/q.js did not work as expected. It seemed to demand I have some other pre-requisites. The only way I was able to get a running version was to make a fake Web Project in Visual Studio and download it through NuGet. A dist folder that has this 'compiled' version would really be nice.
Then, lead strong with samples from the #the-beginning part. Tell us what a promise is and why we want one, then show us how to get one.

So it would briefly look like this;

A promise is .... You can get a promise like this ... You can run this code to see an example.

What is Q.fcall? Why is it called fcall? That's weird. Why not just Q.call? Or Q(fn)? What is valid to pass through an fcall?

These are all questions that went through my head as I was reading through it. I do think fcall is a strange name for the function, and I would honestly prefer it be something that satisfied my own OCD more like Q.invoke or Q.start(fn), but I'm not the genius who wrote the code, so I don't get the right to say anything on that matter.

And then a short snippet that shows a real world use that can be copied and pasted without the need for server side technology. Something the user could quickly put up in a jsbin or a jsfiddle. Perhaps even lightweight cdn links so that it becomes a little less distracting to get the library into those external code runners (note. I am not suggesting you host a cdn. I am merely stating that if you take a https://raw.githubusercontent.com/kriskowal/q/v1/q.js and change the url to https://rawgithub.com/kriskowal/q/v1/q.js you get a url that is accessible to things like jsBin and jsFiddle.)

So you could start off with a sample file that looked something like this ...

<html>
    <head>
        <title>Q.js</title>
        <script src="https://code.jquery.com/jquery-2.1.1.min.js"></script>

        <!-- example, demonstrative url only. do not use in production. -->
        <script src="https://rawgithub.com/kriskowal/q/v1/q.js"></script>

        <script type="text/javascript">
           $(function(){
              // show us a real deferrable use, show us Q in action.
           });
        </script>
   </head>
   <body>
        // obviously, body content is here.
    </body>
</html>

Bam

I can take that to the bank, I can almost copy it right over to jsbin, or segment it up for jsfiddle, or http://codepen.io very quickly, now I'm prepared to start just trying things.

Take a look at how they are presenting the idea of `MVVM` over at `knockoutjs`.

MVVM

There is actually a lot of information here quickly taught to me. While you may not be able to a _runnable example__, something that quickly breaks apart the pieces of the puzzle would make most of the rest of the documentation fall together in line much faster.

What is happening here on the knockoutjs page, though? A few things;

They show me a real world example.

This is super important. Something I would actually want to see in the real world. Not foo, not bar, they are presenting a set of code that relates to something any of us as programmers have probably done before - a general shopping cart/ticket/storage system. It's basic, it's cut and dry, it's extremely simple. It triggers a lot of memory.
The point out the important pieces that come from their library

There is a distinct differentiation in what comes from knockout.js and just javascript. The little tool tip call outs accomplish this. I instantly see what the code is intending to accomplish, and how it is divided up. They have subconsciously gotten my mind to start focusing on their functions instead of my own. With those little bubbles, my attention is now on data-bind and ko.applyBindings.
I can write this exact code into an HTML file, and simply including jquery.js and knockout.js, and run it.

This is the part where I felt like Q falls the furthest behind. I had a really hard time finding something that could just run and try. There was a lot of wiring and collecting involved. I tried to get it all set up on a jsbin to use for some testing, but it was honestly a lot harder than that.

Tying it together

The #the-beginning part really fell short when it started assuming I grasped what it meant by returns a promise of 10. What? Huh? I was scratching my head, lost in thought.

I think the first fully composed 'example' I saw that started to make sense was the 5th code block of https://github.com/kriskowal/q#using-deferreds.

Anyway, I hope some of that helps you a bit in thinking of how you're going to piece together new documentation, if you truly are aiming to do that. I am going to keep studying Q.js very hard, because it's slicker than boiled okra right now, and if I get to a point where I feel confident that I even know what the hell I am talking about, I will try to contribute.

You ever not know you needed something and then bam! Game changer?

Hello, my name is Kurt, and I'm a software architect and producer. I was a bit amused to find this (#543) in my inbox this morning, because yesterday I found Q completely by accident while looking for something unrelated on github, and for some reason was intrigued enough by the README to jump over and take a look at the documentation. And I that is what sold me on the idea in about 30 seconds flat. I found it not just readable and usable, but that it described the base paradigm so strongly in the first half page or so that the rest of it almost becomes superfluous once you understand what the authors of the code are getting at.

Any additional documentation I would expect to see at the code level, probably as a folder of usable tests with correct markup on the classes etc. as an example. Maybe with a nice index page as a jumping off point that explains what the test code does and why, and references the correct part of the online docs.

That is my 2c worth - the only value I am claiming to bring to the conversation might be my professional first impression. I scheduled a block of time for later this week to stop the world and take a deep dive into the subject which is unusual, and I forwarded a link to the docs and github source to my javascript users right then and there.

It isn't a performance or security killer is it? I sincerely hope not :)

Cheers! K

Thanks to everyone in this thread for the kind and encouraging words :). They are awesome.

and for some reason was intrigued enough by the README to jump over and take a look at the documentation. And I that is what sold me on the idea in about 30 seconds flat.

To clarify, when you say "documentation" are you talking about the README, or the API reference? You kind of make it sound like the readme and the documentation are different, which has me a bit confused.

It isn't a performance or security killer is it? I sincerely hope not :)

At present, even with my poor understanding, I have seen nothing but improved performance from using Q.

To clarify, when you say "documentation" are you talking about the README, or the API reference? You kind of make it sound like the readme and the documentation are different, which has me a bit confused.

I kind of mean both. The fact that it is split between different sections may be part of my confusion. I also attribute my sheer lack of experience to it, so bear that in mind. I am giving you the perspective from someone who is not even close to your level, if that makes any sense.

Oh, look at that! I overlooked the API reference, though I was just getting a view from 10k feet in passing.

I saw README on github and did a bit of a double take when I realized what was being built and how handy it could be, and then jumped to http://documentup.com and browsed around for a few minutes. I was properly impressed, but maybe I am just too easy. It is still possible that in a couple of days when I start trying to build some code I'll get frustrated. I don't write a lot of javascript anymore, or anything else that doesn't compile to be honest. Most of my js time in the last few years has been debugging other people's client side snafus, and trying to figure out what in the world someone did to my perfectly elegant spec ;)

The Q here sort of reminds me of something from my programming past, but I can't put my finger on it. My memory isn't what it used to be.

Cheers (by the way, I am going to have to leave this fascinating conversation because I get to move house! Off this darned mountain and back to Santa Cruz! Take care, and don't forget - not everything has to be a closure!)

I am extremely grateful that the project contributors and creator here at Q.js found my comments as the edifying statements they were intended to be, and not jabs at their ability. I am a verbose and outspoken person, and I have had instances in the past where, when I present something to a project, I am met with intense disdain as someone who has no right to comment on it.

@kurtflint Q makes me think of when I first dabbled in programming at pre-junior high, when I played with LOGOS in the school lab. I do not know why. When I am working with Q, I just have these flashbacks to working extremely hard to get that little turtle to move, to get it to do one simple thing, but the overwhelming and exciting satisfaction when I got it to work, and follow a sequence of events to complete the puzzle. I totally get what nostalgia you're talking about.

Also, @kurtflint when I first got Q.js to work 'properly', I looked at the performance boost, and it was considerable. In fact I would say my program loads over 10x faster since I got it wired right, since I don't have to use any waiting or strange loading scripts.

This was pretty much my face:

thank you for bringing up this issue. I too find it difficult to understand how to use Q after reading the readme article.

I am guess, if I have asynchronous function myAsyncFunc(), then I could enhance with Q by Q.fcall(myAsyncFunc).then(resolve(value),reject(err)); Is it what Q is trying to achieve?

ciel, could you kindly show us hello world sample code of using Q?

kriskowal / q

Some more "For Dummies" examples #543

Bam

Take a look at how they are presenting the idea of `MVVM` over at `knockoutjs`.

Tying it together

kriskowal / q

Some more "For Dummies" examples #543

Bam

Take a look at how they are presenting the idea of MVVM over at knockoutjs.

Tying it together

Take a look at how they are presenting the idea of `MVVM` over at `knockoutjs`.