The Aurelia documentation has received a major overhaul, making it more comprehensive and user-friendly than ever before.
While we like to think our docs for Aurelia 2 are already pretty good, we know that there’s always room for improvement. That’s why we’ve been hard at work making them even better. Since we debuted our new docs system some time ago, Aurelia 2 has seen a lot of changes, and we wanted to ensure our documentation kept pace with those updates.
You could call it a spring cleaning of sorts, but we went further than that. We’ve added new sections, improved existing content, and made it easier to find what you need. As we edge closer to the release candidate phase, we wanted to ensure that our documentation is as polished and comprehensive as possible (dramatically changing the docs during a stability phase is not a good idea).
One of the most significant and subtle changes is the tone of voice. We wanted to make the documentation more approachable and friendly, while still being informative and professional. We believe that this new tone will make it easier for developers of all skill levels to understand and use Aurelia effectively. The previous docs were not bad, but they were a bit dry and formal in some parts, overly verbose in others, and we wanted to strike a better balance. We hope you like the new tone as much as we do (it’s something we are still working on, so please let us know if you have any feedback).
What’s New?
An Aurelia phiosophy
We’ve added a new section that outlines the core philosophy of Aurelia. It was inspired by the Ruby on Rails doctrine, which passionately talks about the principles of Rails. We wanted to do something similar for Aurelia, so we created a section that explains our philosophy and how it shapes the framework.
A lot of the items in our philosophy are things that anyone who has used Aurelia before will immediately identify with. We believe that Aurelia should be easy to use, flexible, and powerful. We also believe in the importance of conventions over configuration, and that developers should be able to focus on building their applications without getting bogged down in unnecessary complexity or contending with breaking changes every few months.
Hopefully this section will not only ignite a passion for Aurelia in newcomers, but also serve as a reminder of what makes Aurelia special for those who have been using it for a while.
Developing with AI
We’ve added a new section that explores how to use AI tools to enhance your Aurelia development experience. This section provides tips and tricks for using AI to write code, generate documentation, and work with tools that have become the new norm for developers. We believe that AI can be a powerful ally in the development process, and we want to help you make the most of it.
While these tools are still evolving, we think it’s important to start exploring how they can be used in conjunction with Aurelia. Due to how they are trained, AI tools can recommend outdated patterns, hallucinate package names and get things wrong. This section aims to help you navigate these challenges and use AI effectively in your Aurelia projects.
This section is still a work in progress, and we welcome your feedback and suggestions. But once again, credit where credit is due, this section was inspired by the Angular documentation, which has a similar section that we found very helpful.
Essentials
We’ve added a new section that covers the essential concepts and features of Aurelia. This section serves as a quick reference for developers who are getting started with Aurelia or need a refresher on the key aspects of the framework. It includes information on the core building blocks of Aurelia, such as components, templates and dependency injection.
We realized with our previous documentation that some of the more advanced topics were not as accessible to newcomers. This section aims to bridge that gap and provide a solid foundation for understanding Aurelia. They are now front and center in the documentation, making it easier to find and understand the core concepts of Aurelia right alongside the getting started guide.
Video content
As some of you know we have been working on a series of video tutorials to complement the documentation. Exploring specific topics and we have a few videos already available with quite a few more coming out in the coming weeks and months. These videos are designed to provide a more visual and interactive way to learn Aurelia, and we hope they will be a valuable resource for developers of all skill levels.
Cleanup and Improvements
In addition to the new content, we’ve also made a number of cleanup and improvements throughout the documentation. This includes fixing broken links, updating outdated information, and improving the overall organization of the content. Our goal is to make the documentation as clear and helpful as possible, and we appreciate your feedback as we continue to refine it.
Notable improvements include:
- Leveraging Mermaid to generate diagrams for the documentation, making it easier to understand complex concepts visually.
- Improving the search functionality to make it easier to find relevant information quickly.
- Enhancing the navigation structure to make it more intuitive and user-friendly.
- Adding more examples and code snippets to illustrate key concepts and features.
- Improving the overall readability and formatting of the documentation to make it more accessible.
- Cleaning up the Quick Start guide to make it more concise and focused.
- Simplifying the helo world example to better illustrate the core concepts of Aurelia and keep it on one page.
- Ensuring APIs and features around custom elements, custom attributes, and value converters are clearly documented and easy to understand.
- Better code examples that are more relevant and easier to follow.
- Better documentation around testing, including mocking and stubbing, to help developers write effective tests for their Aurelia applications.
- Improved documentation around third party library integration (one of Aurelia’s strengths) to help developers understand how to use Aurelia with popular libraries and frameworks.
- Cleaned up and improved our recipes section which details how to integrate GraphQL, Firebase, progressive web apps, Tailwind and more with Aurelia. Ensuring that the recommendations are up to date and relevant.
- Cleaned up the tutorials section to ensure that the tutorials are up to date and relevant, and that they cover the latest features of Aurelia. This includes updating the integration examples for React, Svelte and Vue to ensure they are relevant and up to date.
Oh, and we also made some improvements and fixes to the Aurelia 1 documentation, ensuring that it is still relevant and useful for those who are using Aurelia 1.
What’s Next?
We are committed to continuously improving the Aurelia documentation, and we have a number of exciting updates planned for the future. Some of the things we are working on include:
- Adding more in-depth tutorials and guides to help developers get the most out of Aurelia.
- Expanding the recipes section to cover more use cases and scenarios.
- Interactive playgrounds for trying out Aurelia code snippets directly in the documentation.
The goal with the Aurelia 2 docs was always to make them the best docs possible, and we are committed to achieving that goal through continuous improvement and iteration. We believe that good documentation is essential for a successful framework, and we are dedicated to providing the best possible experience for our users.
A thought that has been been in our minds is translating the documentation into other languages. We know that Aurelia has a global community, and we want to make the documentation accessible to as many people as possible. While this is not an immediately planned priority, we are open to exploring this in the future. If you are interested in helping with translations or have suggestions for languages to prioritize, please let us know.
Feedback and Contributions
We welcome your feedback and contributions to the documentation. If you have suggestions for improvements, find any issues, or want to contribute new content, please open an issue or pull request on our GitHub repository . We are always looking for ways to improve the documentation, and your input is invaluable in helping us achieve that goal. No pull request is too small, and every contribution helps make Aurelia better for everyone.
You can also join our Discord community to discuss the documentation and share your thoughts with other Aurelia developers. We love hearing from you and appreciate your support in making Aurelia the best it can be. Or you can engage with the team and community on Discourse at https://discourse.aurelia.io .