Reorganizing Content

[mehulkar]

Looking through the guides, I think the nav structure could look like this:

Intro
  - Ember CLI
CLI Commands
  - /index (links to full API docs and references `--help`
  - new
  - addon
  - install
  - serve
  - build
  - generate
  - test
Build Pipeline
  - Builds & Rebuilds
  - Asset compilation
  - Dependencies
  - Addons (for merging behavior)
  - Plugins (Broccoli intro)
  - Looking Forward (Ember Auto Import & Embroider)
Addons
  - Structure
  - Dependencies
  - Blueprints
  - In-Repo
  - Documenting
API Documentation
  - CLI
  - Addon (aka `index.js` export)
Configuration
  - .ember-cli file
  - ember-cli-build.js
  - ember-cli-update.json
Troubleshooting
  - Windows
  - Vagrant
  - Debugging
  - Performance
  - Updating

Some other things that I can't find a place to put are

• FastBoot: i.e. how to handle FastBoot cases without including FB as a dependency and how to write tests for FastBoot
• Testing (running tests at localhost:4200/tests, the fact that the app is mounted in a div, not an iframe, etc)

[locks]

I think a proper proposal would be an RFC, like the one for the Guides restructure, or the one for the current CLI Guides restructure.

[mehulkar]

I can understand where you're coming from, but I don't think better docs is really something the community needs to buy into (which is the purpose of an RFC). If this proposed restructure is too heavy-handed to do without an RFC according to the learning team, I'll just close this issue, but that would leave me very disappointed 😢

[mehulkar]

To be clear, I would not be able to dedicate time to go through the RFC process for this (especially since it's been unfruitful for me already).

[kategengler]

RFCs aren't just for community buy-in. They provide awareness of changes in the community and between all the ember teams. As @locks points out, the current CLI guides restructure was RFC'd not that long ago, so why would we suddenly abandon our process? https://emberjs.github.io/rfcs/0120-cli-guides.html

[mehulkar]

@kategengler Fair enough, I didn't know that the current structure was created through the RFC process, thanks for pointing that out. The precedent changes my mind that this restructure would make sense to go through RFC (which is still sad, but 🤷‍♂).

Since I'm not willing to put in that kind of time though, I think it's best to just close this and continue opening specific issues about what's missing. What do you think?

[Gaurav0]

@mehulkar I'd like to see this move forward as an RFC. If you and I can find a time to talk, I can discuss taking over writing the RFC with your help and finding a learning team champion.