I’ve been talking about exactly this for a while with some other folks at LinkedIn, though unfortunately it’s still just in the “talking about it” phase. I’ve shared with those folks internally and with a handful of folks in the learning team Divio’s Grand Unified Theory of Documentation (worth reading the whole thing, not just my summary below). Divio identifies four quadrants of docs along two axes, which I’ve found very helpful:
- practical vs. theoretical
- studying vs. working
- Tutorials: studying and practical → learning
- Explanation: studying and theoretical → understanding
- How-To: working and practical → problem-solving
- Reference: studying and theoretical → information
My analysis of Ember’s docs today (with the important caveat that this is me wanting to start a conversation, not assigning blame—our learning team works hard and pretty much 100% in volunteer capacity, so I’m deeply grateful for what we have):
Tutorials: great for core, decent for the surrounding ecosystem, just okay for CLI. Our guides are really excellent for coming up to speed on the core framework, some of the best I’ve seen. The CLI tutorial gives you enough to get started, but it’s pretty bare-bones. The surrounding ecosystem (e.g. around other official libraries) varies enormously here.
Reference: pretty good. Our API docs for Ember itself are solid, and the learning team has spent a lot of time over the last year improving on Ember Data and Ember CLI. While there’s still room to improve here, esp. on CLI and Data, I make use of the core API docs all the time and there are only very rarely times when I have to go poke at source code to get things figured out. PROPS.
Explanation: not great. Both @pzuraq and I have slowly worked to fill in some of this on our blogs over the last couple years, but both of us are busy enough that it’s slow going… and it’s also not super discoverable. I’ve recently started thinking about grabbing a domain and consolidating all of those kinds of materials into something we can continue expanding over time, to help address this gap. The core guides don’t cover this stuff, and they also shouldn’t: they’re Tutorial material!—but we need something which does.
How-To: bad. We have almost nothing in this space, and what we do have tends to be years out of date. This is a known issue and has been for a long time, and efforts like the Ember Atlas have never been able to get enough time to really get off the ground. It’s also a very difficult problem to solve well. This requires dedicated time, and in other ecosystems it often comes out of consultancies, for whom pattern guides often serve as a kind of advertising. I honestly don’t have any great ideas for how to solve this.
Again: this isn’t in the least a criticism of our learning team. My hope here is to get a good conversation going about (a) whether folks agree with my assessment here and (b) about how we might make further improvements going forward!