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:
The axes:
practical vs. theoretical
studying vs. working
The categories/quadrants:
Tutorials: studying and practical → learning
Explanation: studying and theoretical → understanding
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!
This is great. I think it’s a pretty solid summary from my experience. Tutorial and reference docs have improved tremendously over the years.
I’d agree lots of “Explanation” material is captured in your blogs and other random hard-to-coalesce places (this board, or discord, for example). Honestly blogs seem like one of the best places to keep it. Moving it to some core documentation resource immediately introduces the risk of neglect because it would add much greater surface area. I think featuring some of these posts in the Ember Times has been really helpful for spreading them. Some sort of common index of popular articles/explanatory resources might be good, though that still needs a good deal of upkeep (modernity, pruning dead links, etc).
How-tos are indeed hard. Still seems to have the same issue as Explanatory material. There’s a lot out there but it’s difficult to surface/index and it gets stale quickly. It also has the added issue of needing more review and filtering (not all patterns should be endorsed). Only idea I’ve ever had was a big monorepo with stripped down community-accepted examples of various concepts. But that could get messy really quickly.
I’d be happy to help out with any related efforts.
I generally agree with your assessment about the availability of certain materials.
For in depth “why” type resources, I encourage everyone to submit those posts to the official Ember blog.
For How-To, one solution is to create a Cookbook section of the Guides. It existed in 1.13-era Guides and I referenced it myself well into 2.0. I believe it was discontinued due to lack of volunteer time/interest when the API changed.
I would be happy to support others who want to write a proposal to add this to the Guides. A proposal would need to lay out the topics that would constitute MVP to ship it, and the criteria for what should and should not be added to it. A cookbook could have a thousand things and it would probably be best if it topped out at 20-30 very short examples. We would also need a group of volunteer writers to make it come to life, or some people who can spend OSS time at work, or a sponsor for a contractor.
We have the tutorial builder that Godfrey wrote, which we could use to make sure the code samples actually work.
If anyone is interested to explore this further, we could set up a call.
This won’t solve everything but could be some low hanging fruit. What if we curate a list of common things developers will eventually encounter and we have a place in the official guides for a stepping stone convention for solving those common things. This way the scope that needs to be maintained remains contained yet also centralized for efforts to keep current/up-to-date.
For example this guide section might include using native <select>, how to manage FormData, validating forms, provider components, modal dialogs, flash messages, etc.
I realize this was the intent of Ember Atlas but I feel as though that is difficult to discover and too open ended. It feels like yet another source of info that could/will become out of date. Having a small set of content in the official guides has the feel of it being up-to-date and offers some marketing to the ideas and solutions that Ember conventions facilitate.
One note: I think “the guides” vs. “the docs” is an important distinction. As the Divio guide suggests, it’s actually quite important to have a “separation of concerns” here: and just as we wouldn’t say that the API docs need to be part of the guides, I’d argue we also shouldn’t make either “how to”/cookbook or “explanation”/deep dives part of the guides either. The guides are great! Trying to push more stuff into them is likely to make them worse (harder to navigate, more unwieldy, more overwhelming). The key is finding a good home for the other materials.
I like the approach both @jenweber and @sukima have suggested here for “cookbook”-style material, I just think it’s very unlikely that the guides specifically are the right home.
Listening to the Australia talk linked from the Divio site, it sounds like our guides are squarely in the how-to end of things. That is certainly how they are used. A tutorial is closer to a closely guided walk-through of a series of tasks to perform a concrete objective, and we have one of those.
The guides work very well indeed to a certain level of depth. It is at the point of deepening, I feel, we sometimes aren’t sure how to proceed, probably because deepening requires a deeper theoretical explanation of what is going on, which is a different kind of presentation that doesn’t fit the tone of the guides.
If I were to focus on one area for improvement, it would be in bringing together, in one identifiable place on the site, the explanations of areas where platform behavior does surface forcefully - routing and tracking come to mind as initial candidates, but we should collect at least a dozen to give it critical mass.
We could also use more wisdom on design - when to choose to use which features and for which tasks. This could be handled as head-on explanation, but wisdom is often taught better obliquely, perhaps through a series of how-to pages for using features together which bring in the design considerations that played into that pattern of use.
So far, operationally, we have counted on industry blogs and YouTube presentations to present explanation and how-to beyond the guides. We could bring articles onto the Ember blog, but for things everybody needs to know to use the platform well, it would be better to consolidate related material into something on the site that people can follow.
I would like to advocate for an official home for such material one that is part of the emberjs.com site. A place where users can click the Docs link and get there.
Emebr JS Guides
API Docs
CLI Guides
Cookbooks
Least that’s my take on things.
Why not Ember Atlas? Simply—that is somewhere else. I can’t easily reference that. I can’t say: look here is a canonical stepping stone of build from. And truthfully I can’t—for the life of me—find it by typing into an address bar. When I have to look something up I just visit emberjs.com—I can imagine there are many like myself who expect the same.
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.