Quest Issue: Reorganization of the Guides into Beginner & Advanced Content

Summary

The Guides are a common learning and documentation resource for beginners specifically, but also for more experienced users. In the past years the Guides have been incrementally updated and improved content-wise and this process is ongoing. We'd like to further iterate on the general structure of the current Guides to improve the learning story for beginners by splitting up the content into Beginner and Advanced sections.

Motivation

In the recent Learning Team meeting we were discussing the reorganisation of the Guides' content to provide an even better learning experience for beginners. We'd like to better highlight crucial topics in the Guides which we believe are necessary for a first understanding of building Ember applications: These topics should be considered as Beginner or Basic content suitable for first learners. Topics which we believe are interesting for more experienced Ember developers should marked as Advanced and be displayed as such in a distinct, visual way.

By creating a clearer distinction between beginner-friendly and more advanced topics we hope to help new learners of Ember to focus on the topics that are essential for their learning experience, while still making the Guides a useful documentation resource for more advanced users.

Also the proposed changes might alleviate related issues in regards to advanced topics and their placement in the Guides. It was mentioned that particular patterns or API might be too well represented and might encourage their abundant use or even their misuse. For example, there is a growing understanding that observers are a part of Ember's API which are useful for only a few, particular use cases. It was suggested in the past that observers might be over- or misused by Ember users due to their mention in the Guides and a better disclaimer or even the removal of the observer section might alleviate the issue. In this case, instead of removing the explanation of observers from the Guides entirely, we'd like to suggest to move them into the Advanced part of the Guides instead, making the distinction between Ember API essentials and this rather power user feature more visible.

What To Do

To get a better understanding of how we want to improve the distinction of beginner and more advanced topics in the Guides, we'd like to start to identify the sum of advanced topics in the current Guides. Once we know more about the amount of advanced topics and their placement, it wil be easier for us to decide how to iterate further on this feature.

Next, we'd like to revisit some of the ideas we had for future feature iterations, including splitting out advanced topics into a sub section per topic (e.g. Models > Advanced), splitting out advanced topics into their own top-level section, providing a UI for showing / hiding beginner vs. advanced content among other suggestions.

Current Open Issues

[ ] Design Request: Highlight Advanced Topics in the Guides
[ ] Flag All Advanced Topics in the Guides Source
[ ] Display Advanced Topics as such in the Guides App

ember-learn / guides-source