Framework: Transperency and visibility of the project

[stalniy]

Hi guys,

I like this library very much and tell about it to everybody who I know, so thank you for creating a great software!
I'm writing this in order to tell that due to fragmentation of repositories it's not clearly visible the progress and activity in Aurelia framework. Why do I think so? I was interviewed by a new client and he told me that his engeneers said that Aurelia is rather dead than developing, they don't see updates, issues, etc (so, the client decided to go ahead with vue.js). But I know that this isn't true.

So, I'd like to suggest to move everything in monorepo and continue to distribute everything as separate libraries via npm. There are several benefits from this:

• it's easy to understand where to submit an issue (only 1 repository, 1 issue tracker)
• it improves TRANSPARENCY of the work (so, people know that library is not dead)
• it will simplify development (no need to switch between projects in order to fix bug in one and then update dependency in another)

Sorry if it's not a sutable place writing such kind of request but I couldn't find a better place for such request.

P.S.: I just want Aurelia to shine

[EisenbergEffect]

We have blog posts almost every week and a weekly newsletter. We also have releases multiple times a month. The Gitter channel is lively and there's plenty of activity elsewhere, including conferences and user groups. We're launching a new site soon and along with that improved documentation and a Discourse. Aurelia downloads and stars continue to increase, along with site visits, consulting/training requests, etc. It's far from dead. We've got big things we're working on and major announcements coming soon.

We've considered a monorepo before, but there are issues with that, not the least of which is that we'd potentially lose all our GitHub stars, which would really be a serious blow for the framework. It's a lot of work to make the change you are suggesting and means we need to stop development while we make that transition. I'm not sure we can do that now. We'll consider it again after the new site launch.

[weagle08]

They don't see a lot of issues and pull requests because rob and the guys got a lot of it right the first time!

[stalniy]

I didn't say that they did something wrong but just wanted to highlight that with the current approach visibility is low for people who does quick screening of different frameworks. And I guess it may be one of the main reason why vue.js has 59000+ starts and Aurelia - 9000+.

That's why I decided to highlght this concern.

[smolinari]

This probably won't go over well and to be honest, I don't mean to be antagonistic. Maybe my comments can help make a bit of a paradigm change for Aurelia, if taken with neutrality and no bias (which I know is really, really hard to do). This is just my own opinion. So here goes...

First let me say, when I started looking for the "right fit" front-end framework for my project (about three years ago), I first found Aurelia (and my project is still in work btw). You might find some posts from me from way back when. I was liking Aurelia, because it was trying to take a fresher direction than Angular 2 at the time, which I didn't like at all. Angular is much too opinionated or rather opinionated in a way I didn't like. But, I quickly got frustrated back then with Aurelia too (and not because of the opinionation), so I kept my eyes open for other opportunities, which caused me to me leave Aurelia.

And, looking over the docs now, seeing how Aurelia has developed over the past few years and watching and seeing how people are responded to, the issue is still there. It is what I call an "air of condescension". I don't think it is intentional. It's more like ingrained. It's how I can explain why Aurelia isn't taking off as it should. Aurelia "speaks down" to me. It's like it is saying, "if you don't understand me, then you are the idiot."

With Vue, and even the React library, the basis of the uptake and popularity is built on humbleness and the dev experience. Yes, believe that or not for React, despite Facebook authoring it. They, as does Vue, do a great job at making most things about the devs and not really about the library per se. It's hard to put in words.

Vue is smart and pragmatic, yet doesn't give me a feeling of "if you don't get it, the problem is yours." The Vue docs and code don't speak to me as if I don't have a clue about anything. The Vue docs are more of a support to master the library for someone who is smart themselves. They hold my hand, but don't pull me like I am the fool. It's more like they push me to dig deeper and to master the framework. Again, it's hard to put in words, but if you follow the Vue world at all, one of its advantages is its docs.

It's not transparency that is the problem with Aurelia. I think it's a light bit of misplaced arrogance.

The problem is also not split out repos either. Both React and Vue are in the same position to some extent. Their core libraries are only part of the MVVM architecture and they have tons of Github stars and a lot of traction. So, making a monolithic framework repo is most definitely not the answer to making Aurelia more popular. I think it's more about progressiveness. It's about choice and letting the devs make it. It's saying, you can choose ours, or choose someone else's. It's about being humble in terms of it's purpose.

Vue was built out of the need for a simple tool for rapid development, which was supposed to be a side project to Angular. Aurelia was built to be a better framework than Angular. Maybe those simple "roots" for getting started are the telling tale of the two stories and why one is growing while the other is floundering? Is it why one has this "air of condescension" and the other doesn't? Maybe.

Again, I don't mean to step on any toes here. It's just my own 2-cent impression. I could very well be wrong, since it is just my opinion. But, it's why I am a Vue.js fan and not an Aurelia fan.

More importantly, if anyone else gets this same or similar "feeling" as I do, they may also be put off at first, when starting to explore and enter the Aurelia world.

As I said, this "position" Aurelia takes isn't really intentional, nor is it terribly bad. It's just how someone new to the framework might feel, when getting started. I see it as a barrier of sorts. If the newb is willing to look past it, they will find a great community and a very decent framework for sure.

Still, I find that barrier is there and it's how I can explain Aurelia's missing acceptance and popularity. Add to that the difficulty of reasoning about two-way data binding and you get why people are flocking to React and Vue, instead of Angular and Aurelia. One-way data binding is easier to reason about and makes for simpler code overall. It also makes for a better architecture (ehem....like Flux, which Vue also uses). 😄

Scott

[EisenbergEffect]

@smolinari Let me be the first to apologize to you for any negative experience you've had. It's never been our desire to be condescending. I take your feedback very seriously. Here are a few concrete things we're doing to make improvements:

• We're launching a new web site and docs platform that will make it easier for us to improve our documentation over time.
• We've recently re-invigorated our efforts in documentation writing to try to improve existing content and expand the content over the next six months.
• We're planning to launch a Discourse forum to empower our community and leaders to communicate and create a knowledge-base together.
• I've had targeted conversations with various members of our core team to discuss how we are presenting in public and help ensure that we are not "behaving badly".

In the early days of Aurelia, we had to fight pretty hard to justify our existence. To be frank, the way I was personally treated and some members of our team, was one of the worst experiences of my career and has made me question why I've ever bothered with opens source at all. When you are in the middle of that, it's easy to react like a wounded, pinned animal....and we certainly did at times. I can only apologize again and say that we're striving to take a different approach now and are looking forward to improving on all of this.

In the mean time, if you can provide concrete examples of where our docs "come off wrong", please do. We want to fix that. We also invite you to contribute to our project by creating pull requests to make improvements or extend the docs in new ways.

[wshayes]

Rob, we all who use Aurelia really appreciate you and the team's efforts on our behalf. It is amazing how hard people can be on open-source providers (not talking about the comments in this thread that are providing supportive criticism).

You and the team have built and are building an incredible platform. It's always challenging to build, document, provide tools, provide community support at the same time for people who are working on something full-time with a heavily-resourced team which is not what happened with Aurelia as it was built with spare time with volunteer efforts - we've all seen the late night submissions and weekend work you all have put in. I'm working on my own open-source project for biological knowledge representation where we use Aurelia for our websites. It's frustrating for our users because we aren't doing enough fast enough, and it's frustrating for us developing it because we aren't doing enough fast enough in our opinion.

Thank you Rob and team! and thank you to everyone else on this thread as you are trying to help Aurelia become more available to those poor people that don't already use it.

[smolinari]

Thanks Rob. Like I mentioned, the situation isn't intentional at all. You guys and gals aren't behaving badly. I don't mean to put doubt in your minds at all. In fact, I'd say you are handling yourselves fairly well. It's hard to put any one finger on my own impressions and to help you change in some possibly better way, in order to gain the traction you deserve. But, just as a simple mundane example, at the start of the Aurelia docs there is this statement to the question "What is Aurelia?", which is something I just found, because you asked for an example.

Well, it's actually simple.

Is it? This first sentence is already making a judgement for me or rather putting Aurelia in a position of authority over me in a way. What if I don't find Aurelia easy? Do you see what I mean? It isn't something I can go through the docs and point out all the time. It's the position where Aurelia is coming from as a tool in general.

You or other developers might rightly say I am being picky or oversensitive, but this simple sentence at the start of the docs sends an unconscious signal to any dev/ user just starting to use Aurelia.

I guess the first and best suggestion I can give is don't try to imply anything. Aurelia should simply state its goals as to why it's the "next generation" framework. And if you think about that goal too, and you are completely honest to yourself, to even think Aurelia is going to be the "next generation framework", is also being quite presumptuous. Maybe the goals should be redefined to something more modest? All I can recommend is to build off of what is good about Aurelia and not what you think it should be.

Again, all this may be me being picky and too sensitive. Or, maybe I have found an issue that can be fixed. I don't know for sure and I really wish I could be more helpful. I guess a last suggestion is just to try to be more humble about Aurelia and concentrate on as much good and enticing DX as possible. Lead the new devs coming to Aurelia to understand the conceptual magic going on in the background and not only just how to use it. 😄

I wish you all the best of fortune, because anyone who works hard for something they believe in deserves a lot of credit and fortune. Especially, when that work helps others to do their work better.

Scott

[EisenbergEffect]

@smolinari I've pushed out some updates to content based on your feedback. Have a read through this update to the "What is Aurelia?" article here:

http://aurelia.io/hub.html#/doc/article/aurelia/framework/latest/what-is-aurelia

Let me know if you think this is an improvement.

[smolinari]

Looks good. The only thing I can suggest for a further improvement is linking to sections of the docs or other resources, where possible, (mainly in the "Why choose Aurelia" section). Back up what is explained as Aurelia advantages. I was reading and my first impression was, "Give me more!", as in, "How does Aurelia give me this?". 😄

Remember, we are devs. And, in most cases, the elite are easy to attract with good enabling code. It's spreading the base that is hard and that is what is needed to gain a lot of traction. Saying Aurelia is easy to learn is an assumption again. Don't tell me it is easy to learn. Tell me how to learn it easily.

See the difference? 😄

BTW, both React and Vue offer CLIs to generate basic app boilerplate to get started (or in Vue's case a CDN). If Aurelia doesn't have that, I personally would find it hard to consider Aurelia "modern". Downloading zip files is quite old school.

One other suggestion, drop any marketing talk in the rest of the docs (like the first sentence under "Getting Started/Quick Start/ Setup" section.

Aurelia is an amazing framework that embraces simple and clean code without sacrificing power.

In other words, let me as the userland developer make that judgement. Not sure how much more of the marketing jargon is peppered in the docs, but if it is there, remove it. Let the magic of Aurelia speak for itself. Demonstrate it as much as you can. 😄

Scott

[AshleyGrant]

Aurelia has had a CLI for over a year now.

[fabioluz]

My 2-cents here!

One of the first things that I personally liked about Aurelia was the documentation, and I'm talking about (probably) the very first documentation that went online. I remember that the docs weren't just code, they were also telling me that I was building something, with a bit of humor.

However, I know that this isn't practical and can be even boring sometimes, specially when I just want to find a syntax that I don't remember. But it's good emphasise that not all the documentation, or let's say articles, suffers from this problem.

I think, the greatest problem is the article-style documentation. I really hate the fact that I have to navigate to a section to see its subsections. And when I do that, I cannot see the other sections anymore. I love knockout's docs because I can see everything the framework has in the same menu.

So, if Aurelia had a more practical documentation, with less text and more code, most of the problems aforementioned would be solved. The drawback is that would be harder for someone who never used a framework before. Perhaps articles like "What is a Web Component" should be kept, but separated from the real documentation.

Another thing that could really help is a tutorials page like Knockout Tutorials (ko again!). I know that these things are not easy to develop, but they are not that hard either. In short, Aurelia Tutorials would be a gist.run + tests. The hardest part is done already :-) Am I right?

My conclusion:

• Better Docs Platform, no article-style
• Less text, more code. All devs are smart people :-)
• All devs are smart people but some of them never used a framework before - Some articles are necessary
• Aurelia Tutorials

[smolinari]

Aurelia has had a CLI for over a year now.

Great! Then it should be mentioned and used in the "Getting Started" section.

Scott

[EisenbergEffect]

We use the CLI in the second tutorial because we don't want completely new people to have to worry about installing node, the cli and git before they can do "hello world". We've actually gotten a lot of praise from having a getting started that allows people to download, with no machine setup and run an app immediately.

[atsu85]

Based on the discussions I've had with developers who try to get started with Aurelia, the biggest problem related to current Aurelia documentation is that it isn't really clear what are the options (CLI, skeleton projects, simple script tag, gist.run) to get started with Aurelia. IMHO before introducing any specific way to get started with Aurelia, each option must be introduced first, mentioning the benefits and drawbacks and main use-case for each of them.
Smth like

• downloading zip & in-browser transpilation - for experimenting with Aurelia
  
  
  
  • ADVANTAGES: no need to install any front-end related tooling, like Node, npm/yarn
  
  
  • DISADVANTAGES: not suitable for production due to ...
  
  
• CLI (Command Line Interface) - simplest way to get started with real project, that includes minification, bundling, compiling/transpiling ES6 or TypeScript to ES5; styles to CSS,, ...
  
  
  
  • ADVANTAGES: easy to get started with diferent setups
  
  
  • DISADVANTAGES: requires installing Node and Aurelia CLI through npm to developers machine. At the moment doesn't include all the choices, such as ... that are demonstrated by skeleton projects
  
  
• skeleton projects - set of similar Aurelia projects with different tech stack in github (eventually should disappear when CLI supports all the tech stack options)
  
  
  
  • ADVANTAGES: ...
  
  
  • DISADVANTAGES: ...
  
  
• Gist.run - good for reproducing bugs, sharing solutions to (StackOverflow) questions, and tiny experiments
  
  
  
  • ADVANTAGES: no need to install any front-end related tooling, like Node, npm/yarn
  
  
  • DISADVANTAGES: Not suitable for production. Editing experience and speed isn't as good as with Your favorite IDE.
  
  

[atsu85]

Another thing related to my previous comment (and @smolinari's comment) is that developers don't realize that Aurelia even has a CLI.

• CLI isn't mentioned in aurelia.io homepage
• search in current Aurelia hub has no results for neither "CLI" nor "Command Line Interface"

[fabioluz]

I agree with you when you say that all the options may be confusing. Today, Aurelia has 3 options for development:

• Basic Project with run time transpilation
• Skeletons Projects
• CLI

I think that only CLI should be used in the first tutorials because this is what developers are expecting. Skeletons can be presented in later steps.

I don't think that NodeJS requirement is a problem. All other frameworks use CLI as the first option and they require NodeJS as well.

[smolinari]

I agree with fabioluz, KISS!

In the Vue world, they do have the CDN version, but I also work with another framework based on Vue, which is 100% CLI powered and not one dev has complained about the app setup being Node based. It's basically the modern JS dev's development environment.

Scott

[AshleyGrant]

Thanks for the great commentary @smolinari and @fabioluz. There's a lot of good stuff here.

[atsu85]

My comment:

IMHO before introducing any specific way to get started with Aurelia, each option must be introduced first, mentioning the benefits and drawbacks and main use-case for each of them.
Smth like

@fabioluz replied:

I think that only CLI should be used in the first tutorials because this is what developers are expecting. Skeletons can be presented in later steps.

I guess if CLI is introduced first, it wouldn't be too bad either, but current situation where downloading zip + transpiling on fly is introduced first (without mentioning other options), just makes developers scream and probably some of them also run away.

[AshleyGrant]

I think I agreee. Maybe the starter kit could be replaced with a link to gist.run set up to allow the user to play.

[weagle08]

If Aurelia moves to a CLI first tutorial (which would probably help it attract more "casual" developers) I really think the getting started setup without CLI needs to be kept somewhere or put under more advanced usage. I like that the getting started skeletons allowed me to understand exactly how to set up aurelia from scratch, mainly because now when I tried to use the CLI the output structure doesn't fit how I like my client integrated into my node projects and when I tried to modify the cli output I ran into more issues than I cared to figure out how to fix.

As to the marketing language in the docs that was mentioned... It did not come across the same to me as you have stated (that is just a difference in opinion), but these guys are developers same as you who have put in a lot of effort into this framework, how can you fault them for wanting to be compensated for their time and labor? The core Angular team is paid by google and the core react team is paid by facebook. I cannot fault them at all for having marketing language in their docs if that is how you read it.

I never understood the reluctance of devs wanting to pay for software when they themselves are wanting to get paid for writing.. wait for it... SOFTWARE... that logic or lack thereof has baffled me since i started developing

[AshleyGrant]

I need to pay for my Oreos somehow!

[atsu85]

Maybe the starter kit could be replaced with a link to gist.run set up to allow the user to play.

That might be worth considering. I personally haven't seen the value of zip + on-fly transpilation either, but maybe it could be valuable for someone who hasn't used Node, npm etc and isn't familiar with modern FE development tools and doesn't like to install anything just to experiment a bit, so it might still have its place - i'm sure it wasn't created just to add another starter kit to maintain ;)

I think that introducing all the options for developing and experimenting is still worth considering even if CLI is introduced first - just like @weagle08 mentioned:

I like that the getting started skeletons allowed me to understand exactly how to set up aurelia from scratch, mainly because now when I tried to use the CLI the output structure doesn't fit how I like my client integrated into my node projects and when I tried to modify the cli output I ran into more issues than I cared to figure out how to fix.

...I hope that some of them are fixed by now, but i'm not sure.

[EisenbergEffect]

My plan is to make the first getting started tutorial into an all in-browser experience. We're going to build an Aurelia playground directly into the new hub. That will then be usable inside tutorials to teach specific things directly, when desired. I think someone's first experience with Aurelia should be done this way, so they don't have to worry about installing, downloading or doing any setup. They can immediately try it out. Then, the second tutorial would introduce them to the CLI and they could go through a download and install process as part of that.

[smolinari]

I just ran into this interesting article, which also explains other factors for Vue's good traction, and this discussion popped into my mind. The factors mentioned in the article I agree with wholeheartedly and could be food for thought for everyone involved in building Aurelia too. 😄 Maybe Aurelia already fits these factors. I am uncertain about that. If it does. Never mind. 😄

https://sgoel.org/posts/non-technical-reasons-why-i-like-vue/

Scott

[mattpjohnson]

Just wanted to share my $0.02 here.

I think Aurelia could get more visibility if it was added to the CodeSandbox homepage. With Svelte and Dojo on there, I think the team would be open to adding Aurelia. While there is this sandbox which contains a demo for Aurelia, it isn't quite as accessible as a template.

The great thing that CodeSandbox affords is a super low barrier to entry. As Rob mentioned above, newcomers don't want to have to learn a CLI or complex build process just to create a "Hello, World" app.

An additional step that Aurelia could make that would be beneficial (IMO) is to have a third-party component library. Something like Vuetify for Vue, Angular Material, or the dozens for React. Again, this makes it easier for people to hit the ground running with POC projects.

If a component library is something that would interest people then hit me up, I'd be happy to tag-team this with someone.

[obedm503]

I agree with the CodeSandbox idea here, however a component library specific to Aurelia seems unnecessary. It would be better to support cross-framework component libraries to push web components forward.

Aurelia should be shaped so that it works in environments like CodeSandbox instead of building something specific to Aurelia. This would show how aurelia compares to other frameworks on equal footing and hopefully show the simplicity of aurelia's api. An aurelia-specific environment would not show this

[EisenbergEffect]

@bigopon How are we looking for the vCurrent CodeSandbox setup? Do we feel that it's good to go and could we reach back out to them for more official integration into their home page? Same question for Stackblitz.

Note, we do have a component library we've been working on @mattpjohnson You can find it over here: https://github.com/aurelia/ux Most of the work has been done by only one of our team members, so the going is a bit slow. We'd love for you to get involved! It's an area we'd like to grow and that we want to carry over to vNext as well.

[EisenbergEffect]

Also, as a general update, for vNext, the entire codebase is in a single monorepo, so it should be much easier to contribute to than our current version. It's also written with TypeScript and uses their new build system (combined with lerna), so it's really easy to make cross-package changes, build everything and test everything (almost 12,000 unit tests now with approx 82% coverage and climbing) with one or two simple commands. As of last night, we also have nightly builds of vNext as part of our core CI/CD setup. We don't recommend using vNext yet but once it's ready, we believe the new repo, build setup and nightlies are going to make a big difference for everyone who wants to work with us on this project. Thanks for all your patience. It's a big project and a lot of work. We're genuinely very excited about vNext and what the future holds.

[bigopon]

@EisenbergEffect Ideally I think we should have templates for both vCurrent and vNext. I got an example how to submit a new template for codesandbox, I need to actually sit down and do it ... well if anyone wants to help, I'll be very happy.

[EisenbergEffect]

@bigopon I definitely would like to have templates for both vCurrent and vNext. However, once those are set up, I think we should reach out to them about getting their home page and more prominent template list displaying our logo with a link to the vCurrent (for now). Does that make sense?

[bigopon]

Yes. That's something I've been wanting to do too :)