documentation
documentation copied to clipboard

Published 20 hours ago •

Reame
Issues

Documentation Needs

Open plwalters opened this issue 9 years ago • 57 comments

Docs Plan

A Web Developer

[x] What is Aurelia?
[x] Getting Started
[x] A Production Setup
[x] Creating Components
[x] Dependency Injection: Basics
[x] Templating: Basics
[x] Binding: Basics
[x] Router: Basics
[x] Animation: Basics
[x] App Configuration and Startup
[x] HTTP Services
[x] Binding: Value Converters
[x] Binding: Binding Behaviors
[ ] Binding: Advanced Scenarios
[x] Templating: HTML Behaviors Introduction
[x] Templating: Custom Attributes
[x] Templating: Custom Elements
[ ] Templating: Dynamic UI Composition
[ ] Templating: View Resources
[ ] Dependency Injection: Customization
[ ] Cross Component Communication
[ ] Router: Customization
[x] Securing Your App
[ ] Structuring and Organizing Your App
[x] Unit Testing
[x] End-to-End Testing
[x] Bundling Your App for Deploy
[ ] Summary: Conventions
[ ] Summary: Lifecycles
[x] Cheat Sheet
[ ] Glossary
[ ] Errors
[x] Getting Help

Deep Dive

[ ] How to Build the Skeleton from Scratch
[ ] Binding Engine Architecture and Extensibility
[ ] Templating Engine Architecture and Extensibility
[ ] Router Architecture and Extensibility

New To Web Development

[x] What is Aurelia?
[ ] Modern JavaScript and TypeScript
[ ] Modern Tooling
[ ] The Modern DOM
[x] Getting Started
[ ] Next Steps For New Web Developers
[x] Cheat Sheet
[x] Getting Help

A Manager/CTO

[x] What is Aurelia?
[x] Aurelia's Technical Benefits
[ ] Aurelia's Team and Community
[x] Aurelia's Business Advantage
[ ] Onboarding Your Developers

An Architect

[x] What is Aurelia?
[x] Aurelia's Technical Benefits
[ ] Aurelia's Architecture
[ ] Building on Web Standards
[ ] Team Workflow
[ ] Composite Applications
[x] Aurelia's Business Advantage
[ ] Onboarding Your Developers

A Contributor

[ ] Contribution Guidelines
[ ] Your First Pull Request
[ ] Creating or Editing Documentation
[ ] Translating Documentation
[ ] Testing Documentation

A Plugin Author

[ ] Plugins: What and Why?
[ ] Creating a Plugin
[ ] Publishing a Plugin
[ ] Adding Your Plugin Docs to Aurelia's Docs

Integrating with Other Technologies

[ ] Integrating with jQuery
[x] Integrating with Polymer
[ ] Using 3rd Party Web Components
[ ] Using Aurelia Components as Web Components
[ ] Integrating with CSS Frameworks
[ ] Using RequireJS and Bower
[ ] Building a Cordova/PhoneGap App
[ ] Building an Electron App
[ ] Building an NWJS App
[ ] Building a Windows Universal App

A Migrator

[ ] Migrating From Durandal
[ ] Migrating From Angular 1
[ ] Migrating From Angular 2
[ ] Migrating From Caliburn.Micro

Dec 29 '15 22:12 plwalters

I would like to see more about custom DOM events, and the differences between delegate and trigger and why bubble must be enabled when raising a CustomEvent.

Dec 30 '15 19:12 JeroenVinke

@JeroenVinke Good feedback. I believe that would be great content for "Binding: Basics"

Dec 30 '15 19:12 EisenbergEffect

In the article "Templating: Dynamic UI Composition" we not only need to cover things like compose but we need to talk in depth about how to use the compiler directly to do more customized, dynamic UIs.

Dec 30 '15 19:12 EisenbergEffect

In the article "Binding: Basics" we need to make sure to include information about when ref binding values become available. Previously they weren't available until the attached lifecycle callback, but as of the Beta they are now available earlier in the bind lifecycle callback.

Dec 30 '15 19:12 EisenbergEffect

In the article "Templating: HTML Behaviors Introduction" we need to cover a bit about the general mechanism that underlies both Custom Elements and Custom Attributes. As part of that we need to talk about bindable. We should be sure to cover how that works when used as a field decorator and make sure to include examples of supplying options in that case.

Dec 30 '15 19:12 EisenbergEffect

binding basics: delegate vs trigger cc @JeroenVinke

Dec 30 '15 19:12 jdanyow

We should include your SO answer direction in "Binding: Basics"

Dec 30 '15 19:12 EisenbergEffect

Under Web Developer section Integrating Aurelia Help component with third party (Aurelia of course) applications
Under Integrating with Other Technologies Identity Management (see Auth0-Angular as an example)

Dec 30 '15 19:12 adriatic

For "Binding: Basics" be sure to demonstrate how contextual properties work, particularly in the case of call bindings.

Dec 30 '15 20:12 EisenbergEffect

@adriatic Are you referring to using our docs technology to document 3rd party Aurelia plugins and us providing docs on how to do that?

Dec 30 '15 20:12 EisenbergEffect

Are you referring to using our docs technology to ...

Yes - as we are about to finish the document set for http://aurelia-ui-toolkits.github.io/demo-kendo first preview and would love not to continue rolling our own

Dec 30 '15 20:12 adriatic

It would be useful if the documentation was searchable. And if the section headings were linkable.

Dec 30 '15 21:12 stevies

That's in development. Search will take a bit longer but section linking is coming very soon.

Dec 30 '15 21:12 EisenbergEffect

A lot of questions in gitter are centered around the transfer of data in/out of custom elements and in/out to the parent element. There are several different ways to do this(singleton service injection, passing in callbacks, injecting the parent into the child, getting the parent element and getting the view model off of that, message passing, etc.) and it's not clear when to use which, or even which options are available.

Should there be a portion of documentation for best practices for this and other commonly asked questions?

Dec 30 '15 21:12 ostyn

@ostyn What if we added a topic on "Cross Component Collaboration" and covered different techniques and practices?

Dec 30 '15 21:12 EisenbergEffect

What if we added a topic on "Cross Component Collaboration" and covered different techniques and practices?

A very strong vote of support for this proposal

Dec 30 '15 21:12 adriatic

@ostyn @EisenbergEffect - that would be great. This is something I have been wrestling with recently - combining simple custom elements into more specialised composed elements. I can get things working, but really not sure of best practice here - then there are not too many good examples to copy.

Dec 30 '15 21:12 stevies

@EisenbergEffect That would be excellent. I'm glad that others agree.

Dec 30 '15 21:12 ostyn

I've added it to the topic list above.

Dec 30 '15 21:12 EisenbergEffect

Something I think should be in the Web Developer section: "how to start an aurelia app from scratch", i.e. from "I have npm installed" to "aurelia starts up and can be used".

Basically, it'd be about "how we built the skeleton app".

I'm sure it's not just me who are interested in exactly how things fit together but find tearing the skeleton down tedious and would rather see how to build it up from nothing..

Dec 30 '15 23:12 egeland

@egeland - you can find this information (and a lot more) in the Aurelia Guides - website that hosts all accumulated Aurelia Community authored articles.

Note that all these articles are pre-beta and would need to be refreshed, assuming that there is any interest in that data

Dec 30 '15 23:12 adriatic

Here are a couple more suggestions.

Please get the contributor section done first, so others can join in and follow the rules properly to help build up and get this huge...chore..um....job... :smile:...done. If I knew what the contribution process was, I'd also like to help, where I can.

Sorry, this means more work, but add an API reference section explaining the different services/ options/ interfaces etc. offered in Aurelia. I am not even sure those are the right terms, but as a good example of what I mean, please see VueJS' API page. http://vuejs.org/api/

Add a Tutorials section, where contributors can go through certain steps to make something real with Aurelia. These could also be posted as guest blogs on the site too (as added incentive). If you want to take this even further, have a look at Laravel's Laracasts for a good example. https://laracasts.com/ Laravel isn't the best framework, but it is very good and even better, they do a great marketing job and thus, Laravel is the most popular PHP framework by far currently.

And an extra suggestion not really part of this thread, but more a general marketing kind of issue. It would be befitting to the whole project to get the blogs onto the aurelia.io site. :smile:

Scott

Dec 31 '15 05:12 smolinari

+1 for search option.

Dec 31 '15 09:12 activebiz

I'd like to read an article about component styling, also regarding ShadowDOM and style encapsulation (if that's possible).

Also I'm very interested in the contributor section. :smile:

Dec 31 '15 14:12 Thanood

Hi Folk,

Thanks for asking for our input. You guys are really doing great work.

In the architecture section, I think the "building on web standards" section is particularly important. Especially with Es6 Modules and Web Components (nice to see that web components repo show up recently). Following Aurelia through gitter and the blog has been like following a test case for the state of modern javascript. If you can pull together that story into a small section that always expresses the current state of things, I think it will provide a nice window for folk to approach the framework. Much of this information appears in gitter and blogs, but gets stale fast and the overall picture gets fragmented. Having one spot that summarizes things and is always up to date might require a lot of work, but would be very valuable.

In terms of technical content, offline data storage and sync is, I think, one of the main reasons for using a client side framework. I'd put a section on it right after http with fetch.

Right after the two of them and before binding might be a small section on where to put, or how to structure one's data. Aurelia seems pretty agnostic on this, focusing on just being flexible, which is fine, but a reference to skeleton navigation that maybe adds structure to maintain the state of both the router and one child component locally would tie things together nicely before getting into the details of templating.

For what it's worth. Thanks again for asking.

Dec 31 '15 14:12 Cortrah

I've added some additional topics and created a new section

Using Aurelia Components as Web Components How to Build the Skeleton from Scratch Binding Engine Architecture and Extensibility Templating Engine Architecture and Extensibility Router Architecture and Extensibility Structuring and Organizing Your App

Dec 31 '15 14:12 EisenbergEffect

PS I love the cheat sheet

And it looks like the docs repo is being done with gitbook, if I could download a version every so often to put on my kindle for when I'm walking the dog that would be awesome.

thanks again for all

Dec 31 '15 15:12 Cortrah

I was struggling with how to call call $('.form').validate() when the page loads b/c activate() is called before the view model is built and DOM elements are undefined. I finally found an obscure comment about an attach() hook being called after activate() and tried that. Works! It would be REALLY NICE to have more page lifecycle hooks documented better b/c the only hooks discussed are canActivate() and activate(). It took me forever to discover the attach() hook being mentioned on a random post.

Jan 03 '16 07:01 bischofb

Correction on my part. I failed to find this section of the docs. http://aurelia.io/docs.html#/api/home

So, one less suggestion to worry about. :smile:

Scott

Jan 03 '16 10:01 smolinari

We have those docs here: http://aurelia.io/docs.html#/aurelia/framework/1.0.0-beta.1.0.7/doc/article/creating-components But perhaps it's worthwhile to create a separate doc that lists all possible events for both components and router and explain what does and does not happen, when, etc. I'll add a topic for this.

Jan 03 '16 11:01 EisenbergEffect