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

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:
http://thynksoftware.com has all their web software UIs now powered with Aurelia and soon also https://www.hesehus.dk/platform/pim 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 https://github.com/aurelia/framework/issues/798 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.

Frank

1 Like

I am not at all surprised by your comments and at the same time, I am very thankful for them, as it is clear that I need to write some “higher level” explanation first. The article I asked you to verify is pretty "deep in the weds" for a person with medium experience of using together Gitbook and GitHub.

Executive summary

We are in a situation where it is very obvious (to me at least - and others, when they fully realize thee setup I am working on) that our Documentation Development Workflow is more complicated than it should be because we cannot afford the Gitbook license for 24 people. So, I divided the team into Developers and Publishers (the later role is equivalent to the “system integrator” role in the code development process). At the moment, I envision that just you and me can fully support all publishing tasks, leaving the Developers to use the same process that they already use: write markdown files with a tool of their preference and then upload them to GitHub repository as PRs. The Project Leads are responsible for PR merges and daily interactions with Developers on their teams.

Oups - I though this was a private reply! Sorry bout that.

@frankmonroe Such things happen more often than we would like to - however in this specific case, I thought that your post gave me the chance to explain a bit more about what is coming this week :smirk:

@adriatic
I’m using Aurelia since the beginning, and I have to say that for many times I saw myself doing things on the harder way, because no documentation was available. I would love to help to improve the Aurelia documentation, but in my point of view the bigger problem is: how can I teach someone about something that I’m also trying to understand?

For many times I see the posts of @EisenbergEffect saying that they did something cool using another amazing feature of Aurelia. But when I look for that feature documentation, nothing shows up in the search. I bought every single book released about Aurelia, read every page of all of them, and they are always explaining the basic things we can get from the website.

When I go to youtube to look for tutorials, I just find React, Angular and Vue. The only videos I found about aurelia, are the ones that Rob is talking about why Aurelia is so great and follows the web standards, and showing some basic interpolation or bindings.

So I think Aurelia has a great community, that always try to help each other, but all the community suffers the same problem, they can not write about something that they are also trying to understand.

1 Like

Hi @tbnovaes

Thank you for sharing your thoughts as I we do think alike - like the section:

When I go to youtube to look for tutorials, I just find React, Angular and Vue. The only videos I found about aurelia, are the ones that Rob is talking about why Aurelia is so great and follows the web standards, and showing some basic interpolation or bindings.

There is something missing in your analysis that leads to the comparison with other frameworks and that something is money. This is the very unfortunate fact in US, where there is no provision to support a bunch of very smart guys to do something for a lot bigger group of people. Google and Facebook are the rare exception where they are paying the Angular and React developers just to show how “good” they are, while counting on the marketing effect of that “investment”. Aurelia on the other hand was created without a penny (unless you count the incredible efforts by Rob, who spent all that time without a pay, inconveniencing his own family). His effort were noted by members of his core team, who work on Aurelia on their private time, basically repeating what Rob did before them.

My own involvement is different, because being retired and not having the aspirations for making money, I used all of my energy waken up by my admiration for Aurelia’s achievements so far and am trying everything possible to help Aurelia without getting myself involved into core team business - as Aurelia is sufficiently staffed there. However, there is no way that they could afford to write all “higher” level technical documenation of the type that requires Microsoft to hire well over 1000 technical writers. I call this approach “documentation written by application developers for application developers” and while one can say that all of the core team are application developers, that is not the view they will share with you. They are framework developers a specialization very different from application developers.

Lastly, I seriously disagree with your statement:

… they can not write about something that they are also trying to understand.

If you see my efforts so far (resulting with getting 24 great developers, with a lot of experience in using Aurelia framework) being based on my own failure to grasp the presence of the catch 22 syndrome in your conclusion quoted above, you ought to subconsiously at best believe that I am a compete idiot :slight_smile:. Well I am not, and I could myself teach a lot about aurelia, but that approach does not lead to a team of 100 people writing technical documentation. So, my own contribution (as I see it, that is) in offering my organizational skills (as I was VP engineering in several great US software companies for almost 30 years) to organize community members, with the shared understanding that while noone could sufficently contribute individually, as a well organized group with defined tasks, processes and tools to develop the documentation - we all might do the difference.

So, you can view me as a community organizer, who knows a lot about software development in general and almost as much about Aurelia.

2 Likes

@adriatic Just to let clear, I don’t think you are inexperienced or idiot. I respect and support what you are doing for the community.

Second I respect the aurelia core team, and I know that they have been working hard without any financial return (even though I would be happy to pay a monthly subscription for having advanced tutorials created by the core team)

Third, I learned a lot about aurelia myself, and have been using it since its beginning. Not even all lack of documentation was enough to make me move to a trending framework.

In conclusion, I just gave my opinion but I completely respect yours, and I’m not playing against you, but I’m playing by your side. I want to see Aurelia trending as the top frameworks in the market. I’m willing to help the cause as far as can.

1 Like

@tbnovaes apologies if my initial response was too strong - my intent was indeed to explain my motives, the importance of “community organizing” and the very obvious fact that our group consist of people that know a lot about aurelia, while none of them has the resources (free time) to make a positive impact of significance, alone.

It would be great if you decide to join our efforts as well :smile:

@adriatic I would be happy to join it and help as much as I can.

I was learning aurelia by breadcrumbs of blog posts here and there and they were helping a lot. Having used durandal helped as well. But it is true that the current state of documentation is not well suited for the ones who want to get on board now.
I think it is important to retrace those blog posts and videos and incorporate them in AUCS effort.
But mainly i decided to chime in because after I was moved by willingness of comunity to step up and help the core team with docs, I went to stackoverflow and found out that there are a lot of unanswered questions by beginners.
If they don’t get help there, where will they go?
So please, people join me and donate a minute or two a day to check up on questions at SO. It is important.

Hi @tbnovaes

I am very happy to add you as the 25-th member of AUCS team. Please start learning about this project here and let me know about any moment and place where you felt that the navigation through AUCS maze may benefit from improvements.

Welcome :smile:

Thanks for your observations @Alexander-Taran - they confirm the most important aspect of AUCS: while each member of Aurelia Community is interested in helping Aurelia, the individual attempts pale in comparison with contributions by a well organized and focused effort by a large group of motivated Aurelians.

1 Like

Thank you @adriatic I read the posts. I wonder if there is a gitter/slack channel AUCS team to communicate. And also a list of goals/tickets to achieve, where the team can maybe pick one and work on that.