From 50a4ba51baae7f88c5ff364e4191ca6c1bc3766a Mon Sep 17 00:00:00 2001 From: Jen Weber Date: Thu, 30 Apr 2020 19:22:08 -0400 Subject: [PATCH 1/2] Explain divisions between guides --- guides.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/guides.md b/guides.md index 1e714fb..67034de 100644 --- a/guides.md +++ b/guides.md @@ -62,3 +62,27 @@ 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) + +## Determining where content belongs + +There are three sets of Guides the team maintains: + +- [The Ember.js Guides](https://github.com/ember-learn/guides-source) +- [The CLI Guides](https://github.com/ember-learn/cli-guides/) +- [The Deprecation Guides](https://github.com/ember-learn/deprecation-app) + +This section describes some rules of thumb for determining where to put new content, or whether to relocate existing content. + +## The Ember Guides + +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 + +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. + +## The Deprecation Guides + +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. From 0d5f959648ce4645cff49b7659a685c7fdeccf0e Mon Sep 17 00:00:00 2001 From: Jen Weber Date: Thu, 21 May 2020 12:15:24 -0400 Subject: [PATCH 2/2] Apply locks' feedback --- guides.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/guides.md b/guides.md index 67034de..6184d0c 100644 --- a/guides.md +++ b/guides.md @@ -73,16 +73,20 @@ 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 +### The Ember Guides -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. +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 +### The Ember CLI Guides -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. +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. -## The Deprecation Guides +### The Deprecation Guides 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.