Documentation update about framework

[Serhioromano]

They are working on new robust documentation. Hold your breath 😲!

[EisenbergEffect]

@NetanelBasal I agree with you. We've got a lot of work to do. I would love to here some more specifics from you. What information are you looking for that you can't find? We can try to prioritize that if we know what it is.

[NetanelBasal]

I expect a docs like angular have. i really want to know all i can do with this great framework. now the docs page is too general. we need specific API please, so we get more comfortable start using aurelia.

[wshayes]

Rob - thanks for giving us this preview into Aurelia. It looks really interesting (I mean Wow!). Unfortunately, it looks like people expect perfect and complete in a preview, non-production ready (as you so state) framework. The rest of us non-assholes really appreciate this even if we don't speak up much. I'll go back to looking and marveling now.

[EisenbergEffect]

Careful at the name calling please...as frustrating as it can be. I do understand the complaint and we have some plans for pretty substantial docs. It does take a bit of time to get there though....

[NetanelBasal]

Thanks a lot, cant wait....

[mschoneman]

For what it's worth, the things I'd like to see better documented are deployment and (unit) testing. gulp watch is great for local development, but how do I move things to a "production" server. Same thing with running tests. Maybe it's just because I'm getting started on this type of development (previously doing C# app development), but these issues are border line baffling to me.

Thanks.

[Serhioromano]

Regarding docs I would do 2 docs.

1. Auto-generated from comments. Those should be more like API reference. Just list of the methods and short description.
2. Tutorials - those docs are more case related. The same like you have now but covering more cases.

@NetanelBasal I expect a docs like angular have.

@EisenbergEffect Please, not like Angular. Those are terrible docs. I came from Angular and I witness that it is hard to learn anything with those docs.

@mschoneman but how do I move things to a "production" server

It is very simple. Just copy/upload dest folder to your server. I am using either flightplan.js or gulp-s3 to upload all files to the server with a single gulp command. And AWS S3 static site is perfectly enough for Aurelia app.

[NetanelBasal]

What i mean thats they give us all the API that is available , you can give this in better way :)

[mschoneman]

@Serhioromano I understand that I can just upload the files, but they are talking about improving bundling according to the latest blog post. Will the bundled and minifi-ed stuff be what we interact with during regular development (gulp watch) or will that be another step we have to do? Thanks for the pointer to flightplan.js it looks like a tool I should get to know.

I am still trying to learn: what are the best practices? Maybe everybody else already understands this, but I'd like to get a CI server setup with "Publish to Staging" and "Publish to Production" buttons. What's the best way to atomically update a running site? These questions (probably) don't belong in the documentation for Aurelia, but I wouldn't mind somebody pointing me in the right direction.

[wshayes]

@mschoneman Might be good to read up on Gulp and using it for dev and production deployment. Here is a site to get you started: https://github.com/kogakure/gulp-tutorial Gulp will manage compiling your javascript files into one (or more) larger/minified files, optimize your images, aggregate your CSS after any SASS/LESS compilations, etc and then create a 'prod' ready directory for simple copying to a static website server. One of the reasons it's not straightforward to create build documentation for Aurelia (or any web framework) is that there a LOT of ways to build and deploy websites (look at CI sites - they are so flexible it's hard to figure out how to get started sometimes) - many websites also have backend infrastructure that has be managed in sync. Aurelia has a basic gulp file for getting started and indicated they'll provide a grunt file as well - but you'll need to customize anything provided for your own needs.

[Serhioromano]

@mschoneman Here is example how to bundle Aurelia app https://github.com/SAAirey/aurelia-skeleton-navigation-bundling. Is very simple.

I would not recommend to have different builds local and for deployment. I had that in one project and I learned that that was a mistake. It happened very often, that deploy build had some errors unlike local build. Because you always work with local build it always running well. So those 2 build I had was unsynchronized.

Now I have the same build process for local and production with only difference that I add different parameter file with switches off/on debug mode, set API root, etc...

[gogocat]

Will be good to have documentation about how to migrate from Durandal.

[zewa666]

@gogocat few people already tried that and did some notes about it. I guess the best thing would be to create an example Durandal app, with all the interesting things, as a github repo. Then create a second repo with the Aurelia version, including the tutorial, where step by step instructions are added. I'm sure there are a lot of people who'd like to contribute, myself included, but we are missing a good Durandal Example as a source to get started. Feel free to start something like that and I'm sure others will follow

[gogocat]

Zewa666. There is a Durandal starter kit, that already showcase all the Durandal features. I also forked. http://durandaljs.com/get-started.html
The real world issue is any new project, feature work for my clients are hard to decide to stay with Durandal or Aurelia (it is preview). Durandal Inc needs to ensure no customers drop off to use something else...

[zewa666]

@gogocat I know about the official starter kit, yet I had a feeling that porting that one wouldn't yield much more then just taking a look at the skelly demo for Aurelia. The nice thing would be to take something real, like parts of an LOB app, and see how that may be translated to Aurelia

[EisenbergEffect]

We've made some improvements to the docs and are planning more. We're tracking our ideas and plans in another issue, so I'm closing this for now.

[alsoicode]

Django has some of the best documentation I've seen, and it made all the difference when moving away from .NET.

If I were to base the Aurelia documentation style on something, that would be it.