There is never a silver bullet for any problem, especially in software engineering. We all know this.
Over the past year or so, the Ember Learning Core Team has iteratively solved problems by using SMART goals to improve the learning experience for developers in Ember. We were able to completely overhaul the entire underlying tech for the guides and the website without causing churn for the users. We have made it easier than ever to contribute to Ember, by staying focused on something we call “contributor-driven development.”
In some cases, however, we require the knowledge of the other core teams to better carry out the Learning Core Team mission “to empower Ember users to learn, build and teach.” And right now, ember-data is a core area that needs targeted improvement.
Identifying the issue
The goal of the guides on the Ember website are to help the new user successfully use Ember. Ember Data is part of that, and its flexibility is an important part of what makes the Ember.js framework so powerful.
However, I am not currently able to only use the ember-data guides to successfully use ember-data in my app. I know this because I tried to do this, in order to validate the feedback I’d heard from some community users. I was able to confirm what they had reported- I just wasn’t able to do it! At first, I thought maybe it was just me. Then I remembered that I have successfully built applications that used data in other programming languages. So I talked with additional members of the Ember community, and discovered that many other people have similar problems when it comes to ember-data. The documentation just doesn’t work- it seems to suffer from the curse of knowledge.
Now, if you already know how to use ember-data, then maybe the documentation makes sense, because your mind can automatically fill in the missing gaps. For a beginner, however, that knowledge gap is likely to result in an ember-data error that they have no idea how troubleshoot efficiently. The current state of ember-data documentation fails the new user twice, then: first, it doesn’t provide a complete procedure for working with the system when things “should work,” and second, it also fails to provide the troubleshooting documentation that a new user would need to dig themselves out of that hole. So what would you do? Check your node and NPM versions? Nuke everything? Reboot? Give up?
While I’m confident that this hypothetical user would immediately find assistance from someone more knowledgeable on our discord server — we have one of the most dedicated and helpful open-source communities, period — it shouldn’t be this way.
Documentation can provide the happy path
It doesn’t seem to me like there is a happy path for an aspiring self-learning ember-data user. If there is, it’s not documented very well in any official capacity. As a devotee of Ember, a believer in the promise of ember-data, and member of several of our Core Teams, it’s hard to digest that this is the case. But we have to be responsible and radically transparent about the fact that we have released what is, on a fundamental level, an incomplete software product with ember-data.
Accordingly, I firmly believe that documenting the happy path of Ember Data should be the #1 priority of the Ember Data Core Team and that this should be shipped before anything else is done. The Ember Learning Core Team can help with editing and plan for upkeep, but the heart of the documentation for ember-data needs to come from Ember Data Core Team itself.
One thing that would help in this process is to identify the types of users we have in the community based on the needs their apps place on the infrastructure of ember-data. Some example, one might want to distinguish between users with:
- basic needs: I need to build a form and save the responses
- advanced needs: I have data is coming from different back ends, I need to be able to connect all of them, and I need multiple teams working on our ambitious application to all be able to write and maintain this code base.
- customized needs: I am an addon author and I’d like to build a data addon, and need backwards compatibility.
Documentation can help us plan for the future
There is another reason for immediate focus on shoring up the documentation – it makes deprecations and future planning easier. When there is no clearly documented way to do something, the community will figure out (sometimes clever, sometimes not) different ways to do things. Without documentation that shows “the way”, unopinionated chaos rules.
The problem with the unopinionated approach, is that a core team has hard- if not impossible- decisions to make. Do they keep supporting all of the things? Do they make frequent breaking changes that users have to keep up with? Do they burn it all down and start over? In the end, no matter what choice they make, no one is really happy.
Thankfully, Ember has already collectively decided on a path- the opinionated route that allows for innovation and stability. Having the right documentation is an essential part of that.
I think that improving ember-data will require collaboration between the core teams, because ember-data is a cross-cutting concern. So in addition to writing about what needs to be improved, I will also give some ideas for how to make that idea happen.
I have learned that it’s essential to put first things first- in writing. Here are some ideas that I believe would help:
- Identify the goal and mission of ember-data. Write it down, refer to it often.
- Update the documentation to identify the well-lit paths to:
- use ember-data from day 1 of using Ember
- extend ember-data or write addons
- Re-visit the documentation on a regular basis (once a year?) to make sure it’s still current and still makes sense.
- Identify the parts of ember-data that don’t current work well – and be able to reason about why they don’t work (in writing).
- Have a series of deprecation RFCs that include plans for backwards-compatibility- Ember 4.0 will be here before we know it, as is the perpetual nature of time.
I am of the opinion that only after the corrected foundations are there should more advanced work should be taken on- and having usable documentation is what I consider to be foundational work. I can’t help but wonder if perhaps part of the answer is to round out the ember-data core team with team members that are not quite so explicitly focused on the advanced things, so that the foundations are more thoroughly cared for. Then again, a guiding principle of Ember is that we all climb the mountain together- the advanced users create tools that everyone can use, and we all use those same tools. It’s the Ember way.
I am relatively certain that most would expect that I write about accessibility as I did last year. I still believe it should be an essential part of the improvements we make for the Ember.js framework. We need accessible routing. We urgently need to fix the ways in which the framework ecosystem has broken the web. We need to increase our awareness and education about this foundational part of engineering web-based applications. I believe that accessibility is a civil right, and I will continue to pursue the goal of an accessible Ember experience with passion, patience and persistence. It is my sincerest hope that over the past year, I have convinced our community of the necessity of addressing accessibility shortcomings in Ember.js, to the extent that other community members will write about accessibility in their roadmap blog posts, and that I will not be a lone voice.
Author’s Note: This article was written in response to the call for posts for Ember 2019 Roadmap.