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


#1

Assuming that Aurelia community consists of several thousands of users, the response to my several AUCS posts is less than very encouraging. Such outcome matches my experience from some 30 months ago, so it may indicate that our community members love Aurelia, dislike the fact that documentation is less complete, but expect that this issue ought to be addressed by Aurelia proper - not the community.

It would be great if you can respond to this message, and let me know whether

  1. The concept of getting the community members to write selected portions of technical documents is ill-conceived.
  2. The idea is not bad, but it is not feasible due to lack of free time needed to do that
  3. The reason for weak response to this project is something else (please specifiy)

Thanks in advance


#2

Maybe give it a little more time. Today is the first time I’ve been here for a fortnight because it has been Xmas and New Year, and (in the Southern Hemisphere at least) not much happens in that period :slight_smile:


#3

A good advice, @winter_limelight :ok_hand:

Discussions in this discourse site have a lot longer “half-life” than those in Gitter, so my concern that this while issue will simply scroll into the past is not as serious. I do not want to add something each day to keep the discusion alive, as this method will indeed kill it even faster; people do not like to be pestered daily.

Despite the title of this thread (Is the idea of involving the community in writing documentation less than great?), I am quite convinced that short of tripling the size of the Aurelia core team, this is the second best method to help Aurelia as a “movement”. The community writers could be organized and function asynchronusly with respect to core team management and activities - and @EisenbergEffect is already too busy with working full time, managing the core team and writing parts of Aurelia code.

So, yes, I will wait and in the meantime create the complete context needed to facilitate the aurelia community writers.


#4

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 (http://hspi.readthedocs.io/en/latest/) indeed I did so as a marketing tool. :slight_smile:


#5

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


#6

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


#7

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

#8

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


#9

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.


#10

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.


#11

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


#12

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.


#13

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


#15

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.


#16

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.


#17

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.


#18

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.


#19

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 =/


#20

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.


#21

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.