Why Aurelia Struggles to Gain Popularity

Site Feedback
61

I would like to also point out documentation, I’m a big lover of GitHub and use it every single day. What I wish Aurelia would adopt is to provide some quick documentation in each repo right in GitHub. I don’t want to open the Aurelia web site documentation to know what the GitHub repo/plugin does. Also almost none of them, even Aurelia plugins, have demos. I believe that at the very beginning all repos had docs via readme.md and demos (take aurelia/benchmarksfor example, it’s all in there on the first page of GitHub, even the demo). All new repos, nowadays just tell you that it’s part of the Aurelia family and the link is for aurelia.io which doesn’t help much, most people would click the link and close the page once they find that it doesn’t provide info of that plugin/repo. There’s a few Aurelia that I just don’t know or understand what they do, and since there’s no demo neither docs, I don’t bother going on the Aurelia doc site to find what that is… and I can surely assume that a lot of developers do exactly the same as I do and get turned away by not seeing the info they want in the usual place they look.

Take Aurelia/UX for example, I have a rough idea of how it looks like but the link to the Online Playground Gist, just doesn’t do anything on my side (all I see is Playground for Aurelia Ux component as the output), that is a turning me away… I’ve seen a working demo somewhere, but can’t remember where.

On the positive side, I like how the new sandbox & CDN with 2 script tags is going. I see big potential of including them in each of the Aurelia repos. Doing just that, would help in keeping the new developers interested to know more about the plugin. I’m an enthusiasm of Aurelia, unfortunately my work chose Angular (as you can guess for popularity), but I’m still doing quite a lot of work in Aurelia plugins and all of them have demos and docs right in GitHub, if you want to use it, this is what it looks like… Why not do the same for Aurelia itself? I know that not everything is demo(able), but for plugins (like UX), it should definitely have working demos (at minimum a working web page).

For reference the Aurelia plugins I support are Aurelia-Bootstrap-Plugins and Aurelia-Slickgrid, they both have demos and lots of docs, the latter has all it’s docs through Wiki and there’s a ton. Obviously what would be even better is to add the new sandbox instead of just GitHub web pages, but at least you can see the result without leaving GitHub (which is what I am trying to explain in this big post).

5 Likes
62

It would help early adoption if the default Readme.md could explain how to get up and running, preferably without pointing to ANY other gihub (or other) repositories). If there are more than 3 steps, that is too many! A disclaimer and little else does not encourage experimentation :slight_smile:

“Please keep in mind that XXX is still in (pre-)alpha/beta and by no means ready for production (or even development) yet. Many YYY features and ZZZ use cases around the public API are still untested and there will be several breaking changes to come.”

1 Like
63

I found this site recently:

I noticed that there are 12 js frameworks listed on the homepage and Aurelia is not one of them.
If you go to the “Labs” tab you can find Aurelia, there is link to the source on github but it’s very old.

I am not sure how popular the todomvc site is, but having an up to date Aurelia example visible directly on the home page will be another good way to help it gain more popularity.

If i get chance i will create an up to date Aurelia version myself using the CLI / typescript / webpack.

64

Microsoft seem to be educationally steering (young?) developers away from MVC towards Razor Pages (which are not SPAs) to encourage single responsibility principle development though could still use only Identity pages for login/register/logout with an Aurelia (or other framework) SPA

1 Like
65

Thanks again for the feedback. In the last couple of weeks we’ve taken some action to address a few things:

  • Location of Documentation - Interestingly, every repo has had its own documentation, in a standard “docs” folder for years. At various points in time the README files pointed directly to that. However, what we’ve found is that this actually hurt our documentation efforts. For people who wanted to actually fix, add to and create new/better documentation, it made it almost impossible to contribute, resulting in most of the documentation problems we have today. As a result, in the last couple of weeks, we’ve moved all documentation to the “documentation” repo (following another typical pattern for GitHub orgs). What we haven’t done yet is update all the repo README files. I think that makes perfect sense to do. We’ll work to do that in the next week or two so that anyone reading the README files will get pointed to the correct location. But, for a project this size, it’s turned out to not be maintainable (and actually destructive) to spread the documentation out across dozens of repos. For vNext, we have a middle ground that gets us the best of both worlds. Because vNext is being developed in a monorepo, all core libraries, plugins, etc. are in a single repo and all docs pertaining to them are in a “docs” folder within that single repo.
  • Authoring of Documentation - In our documentation, we used some custom markup for code samples and a couple other things. All that has been removed and replaced with simple Markdown which enables it to render correctly on GitHub now and also with enhanced rendering on our site. Furthermore, the documentation is now organized in folders that exactly match the table of contents on the web site. In fact the ToC on the site is generated from the folder structure of the documentation. Furthermore, every folder has a README with a description of what documentation is in that folder, so all folder-views render nicely on GitHub. We’re going to continue to improve this as well.
  • Samples/Examples/Demos - Maintaining samples for a project this large is very challenging. While at Microsoft, I watched the whole company struggle with this exact problem for the entire time I was there. It’s a big challenge when you think about keeping samples up to date, in sync with changes, versioning, organization, etc. We have had some samples in our docs, particularly in the binding documentation for a while, but it has been difficult to maintain and keep working, which is why our samples did not grow to cover more areas. However, new tools like codesandbox.io are making it easier for us to solve this problem. In the last couple of weeks, we’ve removed our custom inline demo solution and moved the entire binding docs over to using codesandbox. We now have a way to organize, maintain, update and share these samples both with integration into the site/docs and independent of the site docs. In fact, if you visit our home page, we just launched an update there in the last couple of days which embeds a few sandboxes directly. We built these sandboxes directly to mirror what we’ve seen on other sites, like React, so we can show how much simpler and cleaner the same thing is with Aurelia.

We’ll continue to work on improving the documentation and samples situation. I’m personally spending time working on it now. There’s a lot of work to do there but I’m trying to chip away at it little by little each week. One of the next things that’s coming up is a simple way for documentation contributors to preview their documentation edits as they would look directly on the web site. It’s not necessary but we’ve heard from a number of people that they want to test it out so they can be sure it looks great both on GitHub and on the web site. So, we’re going to enable that. At the same time, I’ll be writing some new documentation targeted towards contributors (some of you and hopefully more soon :smile:) so that it’s clear how to cotribute both to the codebase and to the documentation.

Finally, everything that we’re improving for our vCurrent documentation is something we’re bringing over for vNext, so that when that launches all of this will be in place from the beginning.

It’s Thanksgiving today in the USA, so let me also take this opportunity to thank all of you for being part of the Aurelia community. Thank you especially to those who are so passionate to see Aurelia improve and for your constant feedback that we value so dearly.

16 Likes
66

Rob, thanks for the great work. I hope you had time to spend relaxing today!

2 Likes
67

Just wanted to follow up. Community member and book author @sean.hunter.aus has been helping us on the README file action item identified above. Thanks to his contribution, we’ve pushed out an incremental update to the aurelia-framework readme file. You can find it in the usual place here:

https://github.com/aurelia/framework

Since we have a lot of repos under the Aurelia org, before we propagate this general pattern across all repos (quite a bit of work), we’d like to get your feedback and make any revisions, to ensure that we’ve got something that you all think is going to be valuable to both you and to people who encounter Aurelia for the first time.

If you get a chance, please have a look, and let us know what you think. Again, thanks for all the passionate feedback here. It really helps us all work together better to make Aurelia the best it can be.

3 Likes
68

The navigation looks fine. Any chance of adding a Quick Start for Net Core 2.1 including links to project templates for the Microsoft Stack users? Net Core 2.2 is just around the corner and looking forward to a Microsoft Open ID Connect based authorization server (https://github.com/aspnet/Announcements/issues/307) :slight_smile:

1 Like
69

Great work! but please consider not calling it Aurelia Script. When I first saw it I thought you are creating a new language. Unless that’s what you are doing (which would be bad) . Looking forward to vNext.

2 Likes
70

Maybe this is little late, but the most problem I had with Aurelia is with unit testing.

First of all, it is difficult to get the test setup right (but I guess that is not Aurelia specific).

Secondly, it seemed that the tests are not running in complete isolation, as often I had this experience that dis/enabling one test affects the other test cases. Here is a similar example.

I hope that it will be better in vNext. Also it would be helpful if a recommendation of test setup comes from Aurelia team. Personally, I don’t care about the test setup as long as it operates in a predictable fashion :slight_smile:

Thank you for the awesome framework :slight_smile:

71

Thanks for the feedback @Sayan751 I think we’ve got this solved already for vNext as we have over 40,000 tests for the framework itself now. We’ll be looking to package up any helpers based on our testing work there and provide those to the community. That said, I think the way vNext is designed just makes testing much easier to begin with as well. It’s definitely something that was on our list to improve.

4 Likes
72

Awesome!! looking forward to it :slight_smile:

73

My issues are documentation on testing & guidance around common testing scenarios

I visit the documentation, and there is a single item called “Configure”, with next to no information in it.
https://aurelia.io/docs/api/testing

Hence for me to work out why my component test that uses an external package in it’s value converter isn’t working, I’m not sure if that’s a webpack, karma or aurelia configuration issue. Hence spending 3x more effort than I should in resolving it.

2 Likes
74

Agreed far from complete. Documentation means different things to different people. A method name and parameters are provided. How to use it is another matter…

75

I think it’s important to always recognise that there are two distinct camps with regards to “getting started”.

Camp ‘A’ is that of the hardened javascript developers, who have used other SPA products in the past, or even simply had months of hands-on experience with different loaders, transpilers, component integration issues, and all the other crap that comes with well written, well structured application development. That’s most of the contributors to these forums.

Then there’s camp ‘B’, where they are relatively new to javascript, are possibly trying to move from the extremely common MVC and ASP.NET Razor page world to that of creating SPAs. They have no experience with loaders, limited or no NPM experience, and even ES6 is relatively new to them (let alone TS), and many are using Visual Studio (not VS Code) and expect to see a project do everything except write their application implementation code.

I believe the vast majority of people fall into category ‘B’. We see in the forums all the questions primarily from camp ‘A’, but that’s because people starting up don’t tend to post questions; if it doesn’t pass the simple “will it bite my hand off” test, it’s dropped and they’ll move onto something far more vanilla with little or no ‘magic’ such as React. They don’t foresee the complexity involved at 90% product completion because they can achieve the first 30% extremely easily. By the time they hit the complexity issues they are locked into the product, and will happily bodge and compromise to deliver a product.

“Popularity” by definition comes after “adoption”.
So I believe that first 30% part is critical in any framework to ensure adoption, encouraging retention, resulting in popularity. Adoption is a complex concept, because someone could be said to be ‘adopting’ a product as soon as they take the time and effort to install it. If they then give up after three hours of struggling… well that’s a major fail on our part.

Aurelia’s release was unfortunately timed to coincide with the mess of JSPM/SystemJS/Webpack1/blah/blah loader battles. As a result it was a complete shemozzle, and even getting started was a nightmare for those with no interest in getting to understand the internals of the loaders. One simple missing line in a config file resulted in days of hunting to work out why your app (which worked yesterday) no longer worked due to some minor version update.
Coupled with the insistence that Aurelia be usable with every flavor of loader, ES6, and TS, made it a nightmare to adopt for all but the most determined in camp ‘A’.

So what now? Well V-Next is going to be awesome, and some of camp ‘A’ will appreciate it, and perhaps a few of camp ‘B’ will notice a few of the benefits if they reach the 30% mark, but I don’t think it will have any effect on the new adopters.
The single module inclusion is a huge opportunity to address this issue, and although it doesn’t work with all browsers, it is usable as a hook to get people started (before they hit the quagmire of loader tooling). We must try to make tooling a no-brainer so they can concentrate on the important thing; developing their application logic. That’s where Aurelia is such a winner, but it’s overshadowed by all of this other confusing ‘crap’.

Documentation is obviously critical, and as has been mentioned earlier, it should be short and succinct. It should also always be clearly labelled with the versions to which it applies! Searching Google for information on validation and unknowingly trying to apply code from 1.2 to a 2.1 framework (or even a 1.3 framework!) is frustrating and guaranteed to turn people off.
Aurelia’s original cheat-sheet was a godsend. It was one of the reasons I adopted it, and to me was an example of the author relating to end users, which bode well for the future.

So we need to focus on the comments by users like @ArchEnemy as I believe his sentiment is key to encouraging adoption. He talks about the hand-holding process, the attraction of simple screen-shots, and the tiny ‘rewards’ that users get from actually seeing something work immediately, rather than after three hours of debugging.
I taught as a university lecturer for six years, and I can say from experience that the skill level of developers follows a bell-curve distribution. We need to start focusing on the 40-70% section instead of the 70-100%, as that’s the best way to build the user base, and less on the people who can find workarounds by themselves.

Anyway, that’s my wurble over. Obviously these are my observations and opinions, and they may be wrong, but at least they hopefully provide points for conversation or debate :smiley:

11 Likes
76

I’d say that’s a pretty darn accurate assessment. FYI Next up on my personal list for docs is reworking our getting started tutorial so that it can be done all in-browser without any downloads, installs, tools, etc. I’m hoping that will significantly improve the experience for Camp B. We’re also continuing to invest in our CLI which we think will help in the transition over to local development with tools. We’ll keep making improvements. Thanks for all the feedback.

4 Likes
77

Something I usually check is what have been done with the framework or library I’m checking out.
While Aurelia have really cool projects, mostly are behind logins. I think the current aurelia showcase is builtwithaurelia.com but it feels outdated.

That’s some of the things I usually check and of course, the docs. The cheatsheet was a blessing on the hardest times, I’ve been on that mess of SystemJS, JSPM, webpack, require and I’m really glad now it’s way better and headed on a good direction.

Thanks to all the Aurelia team for taking the feedback and making such an awesome framework!

2 Likes
78

Agreed. In most cases Aurelia is present and works out of the box based on all the dependencies (mapping all the versions numbers of the different downloads that work robustly and reliably in a typical commercial application is, however, a complex matter and development can be too experimental for widespread use in todays commercial world of tightly controlled time and cost constraints). I was an early adopter of JavaScript 20+ years ago when it came out and noticed complexity increasing without limit as everyone jumped on the bandwagon writing frameworks one after another after another supposedly were written to simplify application development. In those days the main challenge was getting software to work correctly in Internet Explorer due to poor standards compliance (possibly no longer in mass usage except by the most keen of users). Now coders are expected to be loader/bundler experts and this can be a bridge too far. This is nothing to be proud of as undue complexity causes difficulties that should not be deliberately introduced. Elegant software engineering applied to Open Source keeps everything simple, easy to understand, maintain, and push the boundaries and frameworks/applications should not break whatever choice of IDE (sometimes files on a server can be edited using Notepad++ where complex IDEs are not installed). Hardly any software can be understood in its entirety by one person so when modifying Open Source it is essential core features are not unduly complex (or based on dependencies also unduly complex). Best to keep things short and simple :slight_smile:

1 Like
79

Thank you @jsobell you nailed it! I always focus on adoption (because more contributors can even help with your documentation or tutorials or even improving Aurelia on Github so Eisenberg is on the right track for updating the documentation github to be easy-to-contribute). Flexibility is key, you introduce people with easy micro-framework concept of elegant simplicity, then you ALLOW complexity for advanced users without requiring complexity.

Now I’m going to bullet point ideas/notes over the last month, so no one reads a wall-of-text, I don’t want to use up precious developer time:

  • aurelia-cli is very important. Being able to immediately start a project with one single npm install is key for adoption of people with the most basic experiences. Every day we get engineer resumes (granted I am East-coast and don’t live in Silicon Valley), and you could argue that the bell-curve is actually more like the Eiffel tower at the “beginner” section. Everyone knows a little of everything but not very well. Specialization is not possible in an environment that is always changing (and complacency is preferred)
  • aurelia-cli is getting really big (what did my npm console say about how many packages? Did I just read 600 packages?). Keep it simple, or introduce an au-cli-light or something just to get project started. Keep all generators and complex stuff in the other one.
  • I had an issue with generators not working due to some babel-js problem. I couldn’t figure it out, so I just wrote the code manually.
  • A boss wanted to run the app to stare at it and think of ideas. Their laptop is old and due to whatever corporate permissions going on, npm install aurelia-cli was failing and so was our npm install for our project (but it works in other computers).
  • The codesandbox on homepage looks fantastic but the "features"section should probably be moved somewhere near the bottom, or have “highlighted features” that is only 1/4 the size with some bullets so you can see the codesandbox on the same page.
  • As others said above, the cheatsheets are awesome too. Engineers typically skim through stuff first and run code real quick (instant gratification if it works), then come back and do a “full reading” later (you don’t want to lose them in between this step).
  • VSCode documentation/extension website does a great job of leveraging gifs. Screen2gif is a great idea for tutorials and VSCode uses it everywhere.
  • If you’ve ever seen awesome-aurelia I’d highly recommend it. People don’t always know where to go to find things in a new SPA adoption.
  • It’s critical that beginner tutorials show a bit of organization of components. When I first started, I did not realize you can just create a folder posts, create a posts.js, then posts.html, then posts.css and it will get autowired together (with a small import posts.css in the js). That’s really nice. Components simplified! Then you have the bigger tutorials for people who like to follow a storyline, “how to make blog”, “how to make a data science app”.
2 Likes
80

There was a bug in early cli v1 beta, upgrade your global and local cli to latest version. That should be fixed.