ember-learn / ember-learn/guides-source

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

Open
#489 1 comment 1 reaction 0 assignees View on GitHub
Dominant language
HTML
Stars
161
Forks
512
Avg merge
4d 9h
Merged PRs (30d)
4

Description

## 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](https://guides.emberjs.com/release/) to improve the learning story for beginners by splitting up the content into `Beginner` and `Advanced` sections.

## Motivation

In the recent [Learning Team meeting](#xxx) 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 `observer`s 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](https://github.com/emberjs/website/issues/2865). 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](https://github.com/ember-learn/guides-app/issues/260)
- [ ] [Flag All Advanced Topics in the Guides Source](https://github.com/ember-learn/guides-source/issues/191)
- [ ] Display Advanced Topics as such in the Guides App

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.