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

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

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:

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.


@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.

Hi @tbnovaes, I think you are looking for Gitter room aurelia-community. You’re welcome to join us there.
BTW I read bad stories (“rumors?”) about Slack (eg: it does not scale and they “spy” on the data - I prefer Gitter myself).
Welcome to the group @Alexander-Taran.

Thanks @frankmonroe for referencing the Gitter channel : This information is also available in the startup information article I mentioned in my welcome greeting above

I will post the other information @tbnovaes is asking for on coming monday, here in Aurelia Discourse forum and in Aurelia-community Lobby chat room on Gitter.

Thanks @adriatic @frankmonroe

Just for warming up - please check AUCS - projects, teams and repositories (Draft) and follow the links. While not everything is defined, I would appreciate to hear about your experience navigating this maze.

I’m not sure whether this helps but documentation is generally best organised by a few people. As in many areas of life too many cooks spoil the broth and there is there is no shortage of on-line contributors in discussions but we live in a commercially run world and there exist many different expectations as some users are working in education, for their job, and for particular interest itself. I have used Angular so used to writing more code than necessary (eg Controllers, Methods with large numbers of parameters, and $Scope). It is always best to write less code since any code written needs to be thought about and maintained in due course. Aurelia allows far less code to be written than any other framework so technically best. Will this go the same way as Betamax in the VHS/Betamax years ago? It entirely depends if a critical mass of people can find out from the documentation how to use it quickly, effectively, and professionally…

I’ve read the following in order to learn enough to get started but there has been frustration since some references are out of date and NPM packages don’t always play nicely especially as versions have changed since the outset. I particularly like Visual Studio 2017 Community IDE so focusing on Microsoft stack. (NET Core 2. EF Framework Core, SQL Server) using SPA templates since these can be used for best practice in convention programming.