Btw with regards to component vendors and Aurelia
Btw with regards to component vendors and Aurelia
We were talking about the web accessibility directive, not GDPR.
Yeah let me just briefly describe the overall problems, because as an experienced engineer I recognize the elegance of Aurelia (The Einstein philosophy of elegance and simplicity => correct) hence why I adopted it… (no it wasn’t because I had never heard of vue or react at the time! No it wasn’t cuz I have an irrational irritation to strong typing and hated angular2 switch to typescript). I’ll try to be constructive, please don’t take it the wrong way.
- Starting with the TINY “get started” button on the main Aurelia page. haha. Make it bigger!
- Get started takes you to TODO tutorial. Too much setup. Why is it showing me index.html? I don’t care about that. As a beginner I only care about “app.html” and “app.js”. Instead the tutorial should start with “npm install” and “npm install au-cli” or something. Then “au new TodoProj --quicksetupskipallthedamnoptions”.
- Why not just put a pasteable CSS (CDN-hosted link to CSS via link tag) to make the todo app look slick?
- MORE SCREENSHOTS. There are very few screenshots of each code result. Many engineers learn visually rather than reading (great idea on CODEPEN links Mr. Eisenberg!!!). Some people secretly hate reading it seems.
- What the? visual studio is being discussed in the todo tutorial? Most ES engineers (that I know in my industry) use Visual Code or Sublime or notepad++.
- I was comparing to the Vue.js intro tutorial… and I got so bored out of my mind because it’s so lengthy. But they had it right when they started off super simple, super easy install, and then showed a custom component. No custom component / element stuff exists in Aurelia’s tutorial. However, it went on way too long. I don’t have the patience for anything except Chess!
- Oh, Aurelia todo tutorial is telling me about main.js now, I really don’t think I care as a beginner. Au cli should do the bootstrapping for me already. Oh and by the way, “au generate” is broken at this time. Think about tutorials like “twitter” if you can fit your tutorial in 150 characters, even better.
- Put some more tutorials on getting started, basic custom elements. Basic UI elements utilized. There was a section in AureliaCasts about ToastService event-aggregator, that was a great simple tutorial in the middle of a video! How do I create a component quickly and connect a folder of new custom elements?
- Perhaps have a tutorial for “blog post” (but without all the “archives” and other nonsense things of traditional blogs), just show me the router & url-slugs!
- Insert an advanced UI framework tutorial (AureliaCasts was a great tutorial for me, loved it, but I no longer enjoy bootstrap, I am more into Material design now). Maybe you can write a tutorial utilizing Aurelia Material Design (aurelia-materialize-bridge?) showcasing some advanced UI capabilities that engineers today are interested in.
- More advanced tutorials: how do I design a plugin? How should I organize my static assets?
- Demos, codepens, demo links…Have links to cool demo sample websites. The coolest thing I’d want to see first would be to see all big websites using aurelia or some big sample apps using aurelia that look sleek and modern. I saw there was a “aurelia-ux-showcase” and there was no demo link to it, I tried compile, didn’t work, gave up.
@ArchEnemy Thanks for the feedback. It aligns well with a lot of what we’re hearing from others and what we’ve been thinking too. We’ve been doing some core work on our docs infrastructure lately. In the next few days we’ll be deploying with some minor updates but the interesting new thing is that we now have an easy way to put CodeSandbox demos anywhere in our docs…so we’ll be doing more of that. Next up after that is released, I’m going to re-work the Todo tutorial. No downloads, no installs, no configuration…just getting straight to the learning. Our plan is to put CodeSandbox side-by-side in the browser with the tutorial so you can actually learn in the browser. Since we skip all the setup stuff, we can probably replace that with some more interesting additions, such as showing how to create a custom element, like you suggest. I think that’s a great idea. Summary is, we’re working to incrementally address these issues. We’re doing as much as we can for today’s Aurelia and also working to carry all of this forward for our vNext Aurelia as well, so we start out of the gate with that in a more solid position.
From my own experience, initial impressions were very important to me. I needed to be able to get the CLI, ‘new up’ a project, build and run it without issue. This was not the case. I look around many dotnet CMS projects every so often and, after a short while, leave the projects that require too much time to get up and running or cause me to troubleshoot.
First impressions are vital. One needs to be able to:
- Clone repo or CLI a new project
- Install the dependencies
- Run it
This should happen with zero errors and show nothing but good news in the web console of developer tools. This was not my experience. I made some forum posts earlier this year including:
My thoughts are in there.
Aurelia is my framework of choice and it is a bit of a shame it is not much ‘bigger’. It really deserves to be. Show Aurelia’s power as succinctly as possible to first time visitors (or even those revisiting) and do so without that user needing to troubleshoot. It must just work.
I have used Syncfusion for Aurelia for some time with great success. Awesome support when needed.
I’m sure there would be enough people interested in reading an article about their component suite used with Aurelia. Maybe @EisenbergEffect would also be willing to host it on the official blog if you could create one?
I’d absolutely love to have that on the official blog. Just write a post up in normal Mardown and send it to me. I’ll help edit and work with you to get it in @gregoryagu
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).
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
“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.”
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.
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
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 ) 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.
Rob, thanks for the great work. I hope you had time to spend relaxing today!
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:
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.
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)
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.
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
Thank you for the awesome framework
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.