This page is intended to document the processes and high-level decisions around developing the Ember Guides. This is not intended to be a contributing guide, all contributing information should be available in the guides-source CONTRIBUTING.md.
As a general rule we only ever update the documentation for the latest version of the guides. This used to be a technical restriction in the past due to the technical difficulty of updating older guides, but now this policy is primarily to minimise the maintenance burden of the Guides.
The rule to not backport changes has not come out of a lack of resources or time, it is more of an indication of priorities. For example: if it would take 5 hours to backport a large change to the Guides which would be valid for the previous 3 versions of the Guides, it is accepted that those 5 hours would be better spent improving the current Guides instead.
There have been some exceptions to this rule in the past:
- Minor changes that don't cause conflicts
- Documentation that is missing and is not documented anywhere else
- a good example for both of these points was the PR adding Optional Features documentation
- Fixes to broken links
- Fixes to typos
- Fixes to 404s or anything that would affect SEO
All planned exceptions to this rule must be agreed to by the Learning Team and should be agreed in a weekly meeting before any work commences
The following rules of thumb help us organize content. They apply to all Guides (CLI, Ember.js, Ember Data, etc).
- The Guides should show how pieces fit together, not repeat content from the API docs. If a lot of description is given for one single feature, as it works in isolation, it's a sign that it belongs in API docs and should just have a link to it from the Guides.
- We do our best to give new pages names that match their general web development concept, rather than Ember-specific implementation names.
- We aim to help our existing users find and understand Editions. As syntax changes across the board, it's important to give people easy access to materials that help them get up to speed quickly, as well as give newcomers a clue of how to translate older code samples from articles and Q&A into the latest and greatest approach. For Ember.js, these conversion guides will be kept in
Upgrading/Editions, which contains content that will change as Ember grows and new features land. This guide can be linked to from throughout the rest of the Guides, rather than including much conversion content inline. This means that the new user experience is not cluttered with older syntax, but all users can still follow the trail when they need to. - The Guides should be able to be read like a book, providing a thoughtful order that builds upon previous knowledge. Topics that are foundational for understanding other sections should go earlier in the list.
- We follow RFC 431 in order to improve the Guides learning experience. We aim to keep working to improve the learning flow after reaching MVP, and the RFC should not be considered "feature complete." After MVP is close to being reached, more RFCs should be proposed.
The goal of this document is to describe how nested topics in the Ember Guides could improve UX and content navigation.
The Ember Guides support nested topics in the sidebar, which we will use sparingly to organize in-depth content, to a maximum of 3 levels deep.
There have been multiple projects where people asked if there was an opportunity to have one more grouping level, such as for the contributing Guides, A11y Guides, or a Cookbook. With Octane, it became clear that we would need resources like a migration guide, and user feedback indicated that having these migration guides be one page was too overwhelming. Yet, it seemed bad to have "Octane migration" as a top level topic. This is where nesting can help:
Upgrading
How to upgrade
Ember Editions
Octane migration
Intro
Components
...
In this way, we can logically group in-depth content under the right top-level topic, and create digestible articles, but without cluttering the main message.
Having a structure with too many levels can lead to worse navigation, without some guidelines in place. A third level of nesting is only appropriate when there are:
- There are more than 4 possible sub-pages to group together
- The content has already been written, and user feedback indicates that it is too much for one article
- The information is something that every Ember developer should be aware of (i.e. it belongs in the Guides)
There are three sets of Guides the team maintains:
This section describes some rules of thumb for determining where to put new content, or whether to relocate existing content.
The Ember Guides are meant to cover the needs of the majority of Ember users. They focus on runtime features, but may have some build time information. If 80% of people who run ember new would need the information, it should be covered in the Guides.
Deprecated features should not be shown in the latest version.
The Guides are not meant to be exhaustive of Ember's features, but rather they read like a book and give you the "happy path" journey through building an app. In contrast, the API Docs are meant to cover all of Ember's features.
In some cases, a feature may be omitted from the Guides until it has reached some level of improvements to tooling or coherence with a mental model, but this is decided on a case-by-case basis.
The Ember CLI Guides focus on build time concerns, CLI commands, blueprints, and addon development. The majority of build time concerns should be in the CLI guides, with the exception of essential information that someone would need when they are beginning their learning journey. Some information may be duplicated between the CLI Guides and the Ember Guides, in order to better serve new developers.
These guides help developers overcome specific deprecations that they would see when they upgrade their apps. The content can include everything from links to codemods, to specific step-by-step instructions or copy-pastable replacements. The written content is largely driven by what is written in RFCs.