Documentation & Testing

That sounds really sweet! :slight_smile: I’d love it if you could ensure to explain or at least reference the API for what moduleForComponent, subject() and append() all do, because that looks opaque to me (I’m sure you’d do that as our documentation tends to be excellent along that vein).

I think we need to be teaching testing from the get-go, and we could do that by incorporating it into all of our examples on the documentation site. Tests are great because they can illustrate intent, and along with proper documentation, they tell the full story of the architecture of something.

None of the examples on the ember documentation site have tests that I’ve seen, and yet we demand them from ourselves: it’s impossible to become an ember codebase committer without using tests; in fact whenever someone has a problem, we tend to ask them to create a jsbin, which is effectly a micro test environment isolated to that particular context.

I don’t want to sound like a broken record, but the effects of this would be great for Ember’s PR in a tangible sense: wrappering all examples in tests would provide an approachable mechanism for learning Ember because they explain why things happen as they do. Tests provide a CONTEXT for code. It’s the context that educates.

The reason for that is… if all examples and explanations are well tested, as a new user learning Ember from zero to committer all I have to understand is basic javascript and how to use qunit. I can look up any of the API documentation and all of the examples are shown along with tests for the examples working proving they’re doing what they’re doing.

The best part is, the example tests become part of Ember’s test suite, and we know that Ember is hugely tested from an application level, because all of the tests will be exercising as much of the interfaces as we explain. It would also encourage people to write documentation and work on the codebase - to use a marketing term, we’d be building a very soft gradual engagement ramp.

I’m very interested in this, because it’d let me start to contribute to Ember, too :slight_smile: Right now, the ramp up in terms of difficulty is still massively high. It’d be great if we could make the ramp up less steep by simply encouraging people to contribute from the get go. In order to do that, we have to work on the accessibility of it, and I seriously think handing people qunit and saying “learn this to learn Ember” is a great way to do that.