Expand/restructure documentation

[chriskrycho]

Right now everything lives in README.md. This is (a) not sustainable and (b) not very usable.

We should refactor the documentation to live in docs/<various files>.md, and allow the README to be much more svelte.

For a helpful reference on the taxonomy of kinds of documentation, see Steve Losh: Teach, Don't Tell.

Planning

TODO: map out the actual structure of the documentation, as well as the desired content and structure of the README.

Topics we should cover:

• [ ] common problems and workarounds (essentially FAQ)
  • [ ] private (see #212)
  • [ ] generators
  • [ ] current limitations
• [ ] using TypeScript effectively with Ember
• [ ] class behavior
  • [ ] this._super vs. super.<methodName>
  • [ ] constructor and init
  • [ ] positionalParams &c.
• [ ] access modifiers (public, protected, private) (see #226)
• [ ] problems when using excludes

Tooling

• ember-cli-addon-docs

---

An informative comment from my EmberConf workshop feedback form:

It would be cool to have a list of all cases, including generators in the docs for further reference

[oliverlangan]

(From Slack): I was wondering how to do positionalParams with es6 class syntax. Turns out it is easier and cleaner than using reopenClass:

class Foo extends Component {
  static positionalParams = ['bar', 'baz'];
}

[acorncom]

@chriskrycho is this still something you want help with? Saw it listed on the help wanted board but given the age thought it was worth asking ...

[chriskrycho]

Ha! The answer is "sort of"! We did what I originally wrote up here a couple years ago, so I should mark this task as closed, but we need to think about how to integrate (and rework) all our existing materials for the official guides site and migrate it over there. I'll make a new issue to track that!