Is the idea of involving the community in writing documentation less than great?

Honestly, I think most devs hate writing documentation. I know I do. I wrote blog posts to market myself. Although I have written a lot of documentation for one of my projects ( indeed I did so as a marketing tool. :slight_smile:

@alexdresko: Having spent over 40 years in the software industry, my experience is that it is better not to hire a developer that hates writing documentation. Any piece of software created in the professional context is worthless without documentation - a position that I can “soften” in the context of the open source development, where the software development takes place after a full day of work on something else. A good example is our own KendoUI Bridge catalog aplication which is an example of live technical document and which took more time to do than the KendoUI Bridge code. Since I wrote most of that “self-documenting” application I can say that it was a lot more demanding than writing the code :smiley:

1 Like

I agree with @winter_limelight - please don’t give up just yet. I just learned about your initiative today; consider the last few weeks were very sloooow for many.
I, for one, am with you. I will help however I can. I agree with most of what you wrote and so I won’t repeat it all here. I do not understand how Vue (not to name it) can get so much exposure, traction, hype and so on while it’s so difficult to get the same for Aurelia (which IMHO is better suited for LOB applications that require things like DI and IOC for example).
So count me in; however I feel I’m not much qualified and therefore I think I can start by helping editing/QA posts, articles, etc. I think a lot can be written for newcomers to Aurelia and this is where I feel I could help.
Thanks for your work and your initiative.

1 Like

I don’t think that the blog posts are the issue as much as the support on here and gitter. I’m probably going to move on if I post a few questions and they never get answered. Especially if I’m new to frontend frameworks.

I believe there should be a core team member in here answering questions MOST of the time. Not all, most. This is how you “Market” a framework.

A problem I have is… I’ve had the mindset for so long that “I have no business teaching others… Nobody wants to hear what I have to say”. I’m trying my best to get past that. I need to get over that and do some stuff.

@frankmonroe I think Vue has taken off because of the Laravel support. Taylor (the creator of Laravel) openly supports it. This highlights one of the issues Aurelia has. We’ve somehow attached ourselves to .NET and not a whole lot of people use it. And… .NET doesn’t really support us. Most people out there that are creating new products are using PHP, Rails, Java, etc. not .NET. .NET works well for enterprise-level applications. Most of the time enterprise applications lag behind mainstream and bleeding edge tech.

We need experts in different verticals.

  • Aurelia & Rails
  • Aurelia & Laravel
  • Aurelia & PhoneGap
  • Aurelia & .NET

Hello @frankmonroe :smiley:

It is precisely the message like yours that makes my decision to devote the single biggest chunk of my everyday’s life a really worthwhile. The realization you stated as

I do not understand how Vue (not to name it) can get so much exposure, traction, hype and so on while it’s so difficult to get the same for Aurelia (which IMHO is better suited for LOB applications that require things like DI and IOC for example)

is the motivation to get this action started and it will keep me enhustiastic throughout - as I am convinced that it is the ease of “boarding” on Vue, which is mainly caused by a lot of good and sufficient documentation. It is the sufficient part that we are missing here and I will soon share some examples of what we have compare it with what we should have

1 Like

Hello, @TylerJPresley

We did exchange a few thoughts in the past before and I remember liking what you had to say. I also do not want to leave any post in this discussion without my comments. So, I will address your opinion:

I don’t think that the blog posts are the issue as much as the support on here and gitter. I’m probably going to move on if I post a few questions and they never get answered. Especially if I’m new to frontend frameworks.

I believe there should be a core team member in here answering questions MOST of the time. Not all, most. This is how you “Market” a framework.

Eons ago I was working at Visix Software, Inc as a VP engineering selling one of the first ever cross platform toolkit named Galaxy. All development shops of relevance at that time were our customers - and we were selling it at $10000 (yes, for trailing zeros). In a few short years we were one of the most successful young companies in USA and I could never foresee that it is possible to run out of sufficiently smart customers that could use our product without the enormous amount of hand-guidance.

You would clearly belong to the class of a sufficiently smart customer for aurelia - but again, there is not a sufficient amount of such aurelia users, to take us to the needed prominence. So, I am not “buying” your opinion that the solution is there should be a core team member in here answering questions MOST of the time, because while this would make you (and your types) happy it would not enough for folks like me. I care about sufficient amount of examples that illustrate more then the use of a single API, I care about articles about architectural solutions that might apply in my own case - in summary, please try to make the comparison between the documenation for Microsoft’s development tools and Aurelia’s and you should know what I mean.

I will also repeat the basic premise of AUCS: let’s completely unload the task of writing the technical documents and samples from the core team for two reasons:

  1. we (application developers) know how to do that better than core team (framework geeks) members.

  2. our group can scale up nearly indefinitely - their cannot.

I agree. We (competent aurelia folks) need to do something. I will always think the core should be involved. When the core is not actively involved it feels abandoned. People catch on to that quick.

Here’s an idea. We need a list of topics. Digital Ocean nails this. I can subscribe to topic requests from the community and write an article on it if I desire. Another thing they nail is that the articles are on their site. I don’t have to visit 30 blogs to find the bits I need. There needs to be another link for “Topic Suggestions”. On that page you’d have a list of suggested topics and a way to submit new ones. Another idea would be to add up voting to each topic.


@TylerJPresley: EVERYTHING you just suggested is perfect (and already on my (not yet published) list) - including “mimicking” DigitalOcean. Please do stay tuned.

It would certainly be nice if Microsoft did something like suggest Aurelia as the front-end for Web API projects (even just for .NET Core?). Unfortunately I get the sense that Microsoft are more invested in the MVC server-side render approach than in pure APIs.

@winter_limelight : is this and example of Vue Laravel integration? Can you explain to me what would a Laravel (PHP) user benefit from VUE?

Since one category of the Aurelia community project will be Aurelia Integrations, we should create polls for all types of contributions that we could do - and then prioritize them.

There are long standing rumors about tighter integration between Aurelia and Web API Microsoft solution (that is on the core team task list for well over a year, but given the size of the core team, that never gets done. We should forever agree that core team is best used to maintain and expand the aurelia framework - and we should eventually to everything else. This is how Linux became what it is.

I am getting the feeling that Vue is popular with Laravel because (some) people are using it to do progressive enhancement, rather then as a SPA? When I went to check out their website (Vue), that is what I was presented with and it was presented in a nice easy-to-follow demo. Yet this is barely mentioned with Aurelia and that example looks verbose, is buried somewhere in the doco and uses a component, rather than demoing how to do simple binding, or process a form, which is what these type of developers could be looking for.

Hello @Kukks - as a consequence of the discourse’s notification which is uni-directional, I read your opinion in the email :smile:. I do agree with you, as your view of the “Aurelia reality” is as good as any - it is also obvious that my pledge for help was not intended for you.

Damn, I withdrew it as soon as I saw some of my points had been addressed with the roadmap post a few days ago. :wink: It is still a sad reality when I have spent so many countless hours pushing this framework on to people to try out and embrace…
I’ve tried to help out in my own way over the years now. :slight_smile: has all their web software UIs now powered with Aurelia and soon also will be. But I’m afraid unless some clear time-frames are established for those mentioned in the roadmap, they will be my last.

I know that the support for progressive enhancement is being discussed (I do not have the insight into core team’s daily conversations, so my perception can be off).

I am trying to address the issues that can be addressed by the Aurelia users, which (issues) would significantly ease the entry barriers for newcomers. Support for progressive enhancement is not on such list of issues, but our efforts in GAG may provide the needed relief to the core team to implement that feature, once there is a common understanding about its importance.

Hi @adriatic

I had this idea some months ago, or at least something similar… I even created this issue where I listed several features that weren’t mentioned in the docs. I took most of them from StackOverflow, where I spent several hours answering Aurelia questions.

I was intended to solve the whole list but I stopped because the core team said they were rewriting the whole documentation…

1 year ago, Aurelia’s docs were much better than angular’s. Today is the opposite, unfortunately =/

Hi @fabio_luz

You likely understand already that creating, managing and keeping this group “alive and happy” is a lot bigger challenge, that writing all technical content expected to be created here. Luckily, communication skills reduced to written documents are one of my strong assets, developed through dozens of years doing this :smirk:

To be fair, comparing the output of Aurelia and Angular teams is like comparing the car manufacturing results between a 20 people car shop and Ford. Angular is backed by Google, all the key members are full time, well paid employees - and I do not need to point out the differences in this context with Aurelia core team. So, we need not be too critical towards Aurelia team, as what they did is a real miracle. We (Aurelia users who are also developers) are trying to keep the miracle alive.

I totally agree with you. I never wanted to compare Angular to Aurelia. What I meant is that, in the past, Aurelia’s docs were much better than Angular’s, but that’s not true anymore, which is a sad fact. I know that Angular has “investments” that Aurelia does not, which makes any comparison to be unfair.

At some point, Aurelia’s docs stopped evolving because the whole team was focused on developing the framework. Docs is a crucial thing when someone is deciding which framework to use - This is what I wanted to state.

And I agree that we, community members, should be involved in writing documentation, perhaps even in developing a new documentation website.

You can count on me.

Happily :smirk: - please get me your GiHub ID so I can invite you to our GitHub home as described in gag-ready-to-make-first-few-baby-step

My GitHub ID is fabioluz. I’m sending this here in case you didn’t see the private message.

Hello Nick,

I read your message finishing by: … “I will appreciate if you could point to any point in this tutorial that needs more explanation in Comments to Creating and writing AUCS Guide with Gitbook article - even before it is finished.”

I feel inadequate as I struggled to understand the referenced document. I did not find it convenient or productive to write comments in #3 as you suggested as It would have be tedious to reference the appropriate text, so I wrote my comments side-by-side in a Word document, here enclosed.

I think (IMHO) the document you asked me to review is not complete enough for me to review it. I tried to follow, but it jumps from Gitbook’s site to GitHub’s site and it’s not clear if all the steps are to be repeated each time an author creates a new book. Please remember that I am always positive and constructive, do not take any of my comments negatively.

I now see a myriad of automated emails from GitBook’s site indicating your work of today. I will review this now.

Have a nice Sunday evening.


1 Like