I don't want to sound too harsh and I hope you take this the right way but I have to say it clearly: That README you have is worse than useless. I bet it actively pushes people away from your project. The problem is there's just too much in that README that shouldn't be there and then... what should be there isn't.
So what shouldn't be there? Well, most of it. You don't need a whole section of "Advantages over other frameworks" and then a table comparing to other frameworks.
You don't need most of the overview you have. Just picking something random: there's a full table with methods of Q.event. These are details; it's simply too much information that is not helpful to someone who wants a general overview of your project. The same can be said for most of the stuff there. The section on templates is useless for a README: It shows some very specific details (like the fact that there's a Q.Template.load.options.dir) without actually showing a real-world example, because foo, bar, baz, Some/name, and the code actually shown is all synthetic and abstract.
And that's the other problem: It's generic info. And so we get to what the README is missing: A simple, complete, minimal, working example.
And, yes, you end up the README with "Putting it all together", I know. But again, it's an abstract and generic thing. It shows a bunch of code ideas just thrown together for the shake of showing them. Even the comments in that code say things like "you could do this", "you could do that". It doesn't really help.
What you really need is something like a counter and two buttons to increment/decrement, or an input box and a list that gets filtered as you type, or whatever. Something silly and small... but complete and working. You don't need to show off all the features in that example. Just make sure that the code in the example clearly represents the typical way you'd write it and that you can hopefully keep it under 20-25 lines. Make it so simple and self-explanatory that you don't need to add many comments or any at all if possible. Ideally, make it so that you can actually just put that code into CodePen/JSFiddle/JSBin/CodeSandbox/Plunker/WhateverYouPrefer and then link it with "See this example live".
Again, it won't show all the features available and that is fine. But it will give the reader a fairly good idea of the general approach and the feel of using your framework. Because right now, with so much information the README gives a feeling that your framework it's anything but small, that is something complex with lots of abstract options and ways of doing things.
Exactly my thoughts. The whole time scrolling I thought „and now a full example? Ah no, another block of extreme details I dont need“.
If it’s so easy and great - just show me what it looks like
With all this talk about the README, has no one even tried including the js file and USING the framework before commenting?
I should have it up on a CDN, that’s true. How best to include it in one of the JS CDNs? That way people can literally just include it, or click on a jsfiddle link and play around with examples.
I thought the “overview” section was supposed to cover progressively all the main use cases of how to use the framework. So you would get the idea and try it yourself.
> With all this talk about the README, has no one even tried including the js file and USING the framework before commenting?
To be frank, no. That is too much to ask.
The overview, as explained in another comment, fails to be convincing. And you're asking people to spend time and code something up when it isn't even clear if your framework has any real and convincing advantages.
It is you who should create that first working example, which someone can then tinker with and modify.
I also came back here to say something about the README.
I don't like the `Namespace/another/view` that is in there. Just build something else, for all I care even a todo app so I can see what these values would be in a real-life example.
That's a guide and so it has more details. What I was saying is that the README, in a way, needs less details.
Also, that guide still makes the same mistake of using generic examples and names. It's full of foo, 'bar', someOtherEvent, First.onConnect('something', 'here').handle(arg1, arg2), etc and that's not really how you should write documentation.
The README should have one -two, at most- simple but representative and complete example. An example that shows actual usage of something simple enough to be small. See the examples I suggested above. As a companion to that, you can put that same code in JSFiddle and link to it in the README, but keep both the code and link in the README.
As for the documentation, what I said is that the code shown should always be good code, code where names make sense. You may or may not make the effort of putting full JSFiddle examples into your documentation, but the code that you put in the docs should use meaningful names.
Not OP, vut take a look at Zustand: https://zustand-demo.pmnd.rs . IMHO one of the best ways I've seen to showcase a library. It's simple, understandable and even reproducable (code is all there).
It also doesn't make any sense; it feels as if the overview was written by AI and not double-checked by a human. And you can verify this by scrolling down the page and seeing how the writing quality drops off after the comparison table. Why is React marked a "No" on incremental adoption? Of course React supports incremental adoption. Is React really a no on lazy loading? There is React.lazy. React "needs" Redux as a third-party dependency? What? It says React needs a build step, but that's not actually true, and the way that Q constructs nodes looks like the way that React constructs nodes without a build step. If the memory usage / performance on SSR/render truly outperforms these other platforms, let's see some benchmarks rather than just saying so.
Yep, and certainly there are a lot more errors like these (giving enormous benefit of the doubt here, as the document seems to always err on the side of "other library bad")
For so much comparison talk, there are no benchmarks anywhere to be found.
What exactly would the benchmarks measure?
I don't want to sound too harsh and I hope you take this the right way but I have to say it clearly: That README you have is worse than useless. I bet it actively pushes people away from your project. The problem is there's just too much in that README that shouldn't be there and then... what should be there isn't.
So what shouldn't be there? Well, most of it. You don't need a whole section of "Advantages over other frameworks" and then a table comparing to other frameworks.
You don't need most of the overview you have. Just picking something random: there's a full table with methods of Q.event. These are details; it's simply too much information that is not helpful to someone who wants a general overview of your project. The same can be said for most of the stuff there. The section on templates is useless for a README: It shows some very specific details (like the fact that there's a Q.Template.load.options.dir) without actually showing a real-world example, because foo, bar, baz, Some/name, and the code actually shown is all synthetic and abstract.
And that's the other problem: It's generic info. And so we get to what the README is missing: A simple, complete, minimal, working example.
And, yes, you end up the README with "Putting it all together", I know. But again, it's an abstract and generic thing. It shows a bunch of code ideas just thrown together for the shake of showing them. Even the comments in that code say things like "you could do this", "you could do that". It doesn't really help.
What you really need is something like a counter and two buttons to increment/decrement, or an input box and a list that gets filtered as you type, or whatever. Something silly and small... but complete and working. You don't need to show off all the features in that example. Just make sure that the code in the example clearly represents the typical way you'd write it and that you can hopefully keep it under 20-25 lines. Make it so simple and self-explanatory that you don't need to add many comments or any at all if possible. Ideally, make it so that you can actually just put that code into CodePen/JSFiddle/JSBin/CodeSandbox/Plunker/WhateverYouPrefer and then link it with "See this example live".
Again, it won't show all the features available and that is fine. But it will give the reader a fairly good idea of the general approach and the feel of using your framework. Because right now, with so much information the README gives a feeling that your framework it's anything but small, that is something complex with lots of abstract options and ways of doing things.
Exactly my thoughts. The whole time scrolling I thought „and now a full example? Ah no, another block of extreme details I dont need“. If it’s so easy and great - just show me what it looks like
I am confused though about one thing.
With all this talk about the README, has no one even tried including the js file and USING the framework before commenting?
I should have it up on a CDN, that’s true. How best to include it in one of the JS CDNs? That way people can literally just include it, or click on a jsfiddle link and play around with examples.
I thought the “overview” section was supposed to cover progressively all the main use cases of how to use the framework. So you would get the idea and try it yourself.
> With all this talk about the README, has no one even tried including the js file and USING the framework before commenting?
To be frank, no. That is too much to ask.
The overview, as explained in another comment, fails to be convincing. And you're asking people to spend time and code something up when it isn't even clear if your framework has any real and convincing advantages.
It is you who should create that first working example, which someone can then tinker with and modify.
Let's be real here.
The advantages are clear since they are stated up front.
The only question is whether the framework works at all and actually lives up to what the README says.
I agree with you regarding the working example. There should be many of them.
I also came back here to say something about the README.
I don't like the `Namespace/another/view` that is in there. Just build something else, for all I care even a todo app so I can see what these values would be in a real-life example.
Would this be more along the lines of what you might want: https://qbix.com/platform/guide/javascript
No, sorry, not at all.
That's a guide and so it has more details. What I was saying is that the README, in a way, needs less details.
Also, that guide still makes the same mistake of using generic examples and names. It's full of foo, 'bar', someOtherEvent, First.onConnect('something', 'here').handle(arg1, arg2), etc and that's not really how you should write documentation.
Alright, so the README and documentation should really just have a ton of links to jsfiddle examples? That seems like it would be very useful, indeed.
No, I didn't say that.
The README should have one -two, at most- simple but representative and complete example. An example that shows actual usage of something simple enough to be small. See the examples I suggested above. As a companion to that, you can put that same code in JSFiddle and link to it in the README, but keep both the code and link in the README.
As for the documentation, what I said is that the code shown should always be good code, code where names make sense. You may or may not make the effort of putting full JSFiddle examples into your documentation, but the code that you put in the docs should use meaningful names.
Okay let's say I create a lot of examples like this
https://codepen.io/Qbix-Inc/pen/ogjamBy
How to best embed them in github? Are they helpful?
Not OP, vut take a look at Zustand: https://zustand-demo.pmnd.rs . IMHO one of the best ways I've seen to showcase a library. It's simple, understandable and even reproducable (code is all there).
Or just jump to package.json then you know all the deps and what you really dealing with here.
> the feel of using your framework.
It kind of does, however "user" is the one who loads the site with the framework here, not the developer.
It also doesn't make any sense; it feels as if the overview was written by AI and not double-checked by a human. And you can verify this by scrolling down the page and seeing how the writing quality drops off after the comparison table. Why is React marked a "No" on incremental adoption? Of course React supports incremental adoption. Is React really a no on lazy loading? There is React.lazy. React "needs" Redux as a third-party dependency? What? It says React needs a build step, but that's not actually true, and the way that Q constructs nodes looks like the way that React constructs nodes without a build step. If the memory usage / performance on SSR/render truly outperforms these other platforms, let's see some benchmarks rather than just saying so.
Yep, and certainly there are a lot more errors like these (giving enormous benefit of the doubt here, as the document seems to always err on the side of "other library bad")
>dropped into any website
Some example working with other frameworks will be very helpful!
Does it work with JSX?
EDIT: just saw that it only supports .js and .html
Yes, it’s designed to work with web standards. It requires no precompilers for JSX, Typescript etc, that’s one of the things it keeps reiterating.