Aurelia: Documentation Required For Alpha Release

[Vheissu]

With the pending release of Aurelia 2 alpha, we need to ensure that the necessary parts for an alpha release exist in the documentation on docs.aurelia.io. While a lot of work has already been done on documentation, many sections are still empty.

This issue aims not to get all documentation written and completed for an alpha release, but rather determine what essential parts need to be documented for alpha.

General Observations

The navigation structure for documentation is too flat. For some aspects which can get detailed in terms of documentation, I think we need to think smaller and break things up even more. Right now, the "App Basics" section is way too big.

I believe "App Basics" should explain the basics and answer the following questions:

• What is the best way to start a new Aurelia app?
• How do I create components?
• What is the templating syntax and how do I work with different types of data?

I think for things like the router which could be quite detailed and have many subsections, we should take inspiration from the Vuejs documentation which treats the router as its own standalone documentation, as can be seen here.

We should also consider breaking localisation (Aurelia i18n) as well as validation (Aurelia Validation) into more of their own independent-style documentation as these aspects can be quite wordy and benefit from breaking them up.

Discussions and decisions regarding structure can be ongoing and are not essential for an alpha release. However, I do think it is worth keeping in the back of our minds that newcomers might find the current structure to be a massive wall of links which lacks visual separation and requires scanning a massive list to find what you need.

Migration documentation

Another important thing which I do think we should consider for alpha release is a migration section for those coming from v1. Many developers who try out the alpha will most likely already be working with Aurelia v1 or have experienced working with it in the past. This doesn't have to be definitive and can be an evolving document, but we do need to detail how you bootstrap and initialise an Aurelia application is different to v1, how things like PLATFORM.moduleName no longer needed for Webpack support and so on.

Other things like <import>, the changed lifecycle hook names and so on are also other important things to document. Largely, templating and other ways in which you create components and services are familiar and largely the same as v1. Convention plugins and bridges for final release will make migration easier, however, we probably want to encourage developers to use the new names and ways of doing things instead of relying on migration plugins.

Required for Alpha

• [ ] The quick start guide needs to be finished. It has part documentation already, just many of the sections are empty. This will be the introduction to Aurelia 2 for many and is one of the most important required for alpha release.
• [ ] Given Aurelia 2 introduces new conventions for styling as well as things like Shadow DOM and CSS Modules, the section on styling components is essential to detail how these new conventions work and what approaches developers should take when styling components.
• [x] The new router in Aurelia 2 has introduced new concepts and ways of routing which differ from other routers and routing in Aurelia 1. The router section is an essential part of the documentation for alpha release.
• [ ] [Transforming Data With Value Converters](https://docs.aurelia.io/app-basics/transforming-data-with-value-converters), value converters are largely the same from v1. A lot of documentation from v1 could be ported over.
• [ ] [Leveraging Dynamic Composition](https://docs.aurelia.io/app-basics/leveraging-dynamic-composition), Aurelia 2 has changed how composition works since v1.
• [ ] [Building a Reusable Component](https://docs.aurelia.io/app-basics/building-a-reusable-component) is important to show how developers can build components in Aurelia 2
• [ ] [Custom attributes](https://docs.aurelia.io/app-basics/custom-attributes) right now this page appears to focus solely on out-of-the-box attributes but doesn't mention how developers can create their own. We can borrow from v1, as custom attributes do not differ too much (mostly lifecycle hooks).
• [ ] [Cross component communication](https://docs.aurelia.io/app-basics/cross-component-communication) appears to be copied and pasted from v1. This should be straight-forward to convert to Aurelia 2.
• [ ] [Securing an app](https://docs.aurelia.io/app-basics/securing-an-app) already has some great content but is missing a specific example of using router guards to protect different parts of an application.
• [ ] [Testing apps and components](https://docs.aurelia.io/app-basics/testing-apps-and-components) for alpha we can have something basic here. I have content from my book I can port, but testing in v2 is different than v1 and should be explained.
• [ ] [Configuring auth protected routes](https://docs.aurelia.io/examples/routing/configuring-auth-protected-routes) in the examples section, I think showing how you can protect routes with the new router would be useful

Not required for alpha

There are some sections which are more complementary to Aurelia, but not essential for an alpha release. These sections in the documentation can be temporarily disabled. I think the important thing to note here is the alpha will primarily be used by developers already familiar with Aurelia v1 and that we won't be heavily marketing Aurelia 2 to new developers as certain things like AOT, the CLI and other aspects of the framework are still being worked on.

• [ ] [Building a contact manager app](https://docs.aurelia.io/app-basics/building-a-contact-manager-app) it would be nice to have a working example of Aurelia 2 in action, but shouldn't hold up the alpha release.
• [ ] [Tooling](https://docs.aurelia.io/app-basics/tooling) not sure what this section relates to, but tooling is independent from Aurelia itself. In the case of Aurelia-specific tooling via a CLI, this area is still being worked on and right now, things center around npx makes aurelia and everything else is standard Npm commands npm start and npm test
• [ ] [Building a dashboard app](https://docs.aurelia.io/app-basics/building-a-dashboard-app) like the contact manager, it would be nice, but it's not essential.
• [ ] [Calling web services](https://docs.aurelia.io/app-basics/calling-web-services) once again, this is more of an example of Aurelia in action and more useful for newcomers, not existing Aurelia developers.
• [ ] [Integrating 3rd party libraries](https://docs.aurelia.io/app-basics/integrating-3rd-party-libraries) I have a pending pull request here which adds some content to this page, but if we want to not publish this for alpha or expand upon it, that is fine.
• [ ] [Managing app state](https://docs.aurelia.io/app-basics/managing-app-state) once again, probably not needed for alpha. v1 developers are already familiar with ways of managing app state which still apply in v2.
• [ ] [Customizing binding behavior](https://docs.aurelia.io/app-basics/customizing-binding-behavior) binding behaviors are more lower-level things that many do not customise or create outside of what Aurelia already provides.
• [ ] [Adding animation](https://docs.aurelia.io/app-basics/adding-animation) this is an ongoing thing
• [ ] [Overlays, modals and toast](https://docs.aurelia.io/app-basics/overlays-modals-toast) once again, verging into plugin territory and not essential for alpha.
• [ ] [Advanced scenarios](https://docs.aurelia.io/advanced-scenarios) the whole advanced scenarios section is not something needed for alpha

[Vheissu]

Significant documentation on routing has been completed and live on the docs site. A new router section has been created given the router is quite extensive in features and scope.

[Bart76]

I finished a quick start by myself by rewriting the version from Aurelia v1 to Aurelia v2. I am not sure if you want to include more Aurelia 2 specific things in the Todo App, but IMHO it serves its purpose as a simple and quick intro to Aurelia.

I started working on a personal rewrite of the Contact Manager App of Aurelia v1 as well, but I quickly got blocked by missing/failing routing functionality, which is obviously still in development.

I also noticed that the code samples in the "Setting The Title" section of the Routing - Configuration and Setup page are not working. So I took the time and the liberty to check the history of the router.ts file in the @aurelia/router package, and it turns out that the IRouterOptions interface does not seem to have had a title property. Ever. (Well, not since Jürgen Wenzel renamed property useBrowserFragmentHash to useUrlFragmentHash on 2019-08-26 09:12:40. Since you use the useUrlFragmentHash property in your sample code, I assume I do not have to search in earlier commits for the existence of the title property.) Also the INavigatorOptions interface (declared in file navigator.ts in package @aurelia/router), from which IRouterOptions inherits, never seemed to have had a title property at any time in history either. I understand that the Aurelia 2 project is still in alpha development phase, so perhaps the title property is not yet implemented. Nevertheless, I consider it to be somewhat strange that your documentation already seems to document such future features. It is very confusing at least. Can you please share your information about where your title property is described or proposed? Thank you very much in advance.

[Bart76]

I just received an update from @jwx about the IRouterOptions' title property issue, which seems to be ready to merge in a PR for the upcoming alpha release. Thanks a lot. I am looking forward to it. :)