Hello, and welcome to the Ember Atlas, your one stop shop for navigating the world of Ember.js! This book is a community driven project dedicated to documenting all things Ember and providing a place share knowledge. It is meant to work like a curated wiki, gathering as much information as possible, while simultaneously ensuring that information is easy to browse and has an overall consistent flow.
We don't have much content yet, but in time we hope to make the Atlas one of the first places Ember users look whenever they have a question about Ember. If you'd like to contribute, check out the contribution guide or ping us on Discord! We always welcome new guides and ideas 😄
Why a Wiki?
You may be wondering why we need a community wiki. After all, Ember.js is a framework that is about conventions and zero-configuration, and the Ember guides are meant to be the canonical source-of-truth for those conventions. Doesn't having a community wiki run counter to that goal? Will it lead to more fragmentation in the ecosystem, and more confusion instead of less? We don't believe it will, and here's why:
The Atlas and the official Ember Guides are meant to serve different purposes. The guides must:
- Document the recommended, conventional, and beginner-friendly "happy path" for any given feature of Ember.
- Maintain documentation for all previous versions of Ember.
- Ship documentation that is thoroughly reviewed, triple checked, high quality, and battle-tested.
This sets a very high bar for the content that becomes part of the guides, and can be a daunting task to new contributors. It also prevents us from documenting many different intermediate and advanced user stories, which often involve various community addons or techniques.
We won't be able to cover every topic under the sun, but we can try to capture and organize as much community knowledge as possible, especially around common use cases and combinations. We can take the output of the many Discord conversations, Discourse posts, and Stack Overflow answers and put them in one place. We can help pick up the burden that popular addons have, making their tools easy to learn and approach and use with
To that end, the Atlas has some explicit goals and non-goals.
- Fill in the gaps. We should document the most common "paths" that Ember developers tread which aren't documented elsewhere.
- Provide or link to an answer for every question. Developers should be able to turn to the Atlas if they are completely lost, and learn at least a little bit more about what they are trying to do.
- Be accepting of incomplete or in-progress docs. Writing documentation is hard, and sometimes it takes multiple drafts from multiple authors to really nail down a particular topic. Incomplete docs can still be helpful, and can also serve as a starting point for future contributors, so we should work within those constraints.
- Provide a place for experimentation. The Atlas should be a place for new ideas for documentation and guides to grow, and in time possibly upstreamed if they are successful.
- Strive for accurate content. It's not helpful to anyone if documentation is out of date, incomplete, or flat-out wrong. At the same time, it's difficult to gather a lot of content from many contributors and guarantee that everything is always accurate. The Atlas should be as open-by-default to new contributions as possible, and also open to revisions, corrections and updates over time.
- Gather in-depth technical knowledge about Ember.js. The main guides are great for beginner and intermediate users, but there isn't much content for advanced users, and much of what is out there is scattered through random blog posts, gists, and youtube videos. Centralizing this information will help spread knowledge and level of users and contributors.
- Maintain enough organization and curation. It's easy for the signal to get lost in the noise, and that's a big part of the reason the Atlas exists in the first place! However, we also don't want to waste time bike shedding over where something should go. We should always make sure that developers can find the content they're looking for on the Atlas, and regularly review, revise, and edit the content in the wiki, while having an open mindset toward new contributions.