Pillars of DX: Cognitive load, feedback and flow state
Here’s this great paper about developer productivity.
Its premises are correct:
- Flow state is the goal of developer experience
- Managing cognitive load is essential to entering flow state
- Maintaining flow requires feedback
We have to do a bit of lifting to re-situate these goals out of the corporate premise the paper operates from, making the lessons usable for selling developer tools.
There are so many ways to manage cognitive load, and they’re relevant at different stages of the developer journey.
When a repo’s README file has a little code snippet for a basic, working integration, that’s cognitive load being managed. With a copy-and-paste, you can quickly evaluate how that library is working with the rest of your projects. You don’t need to do any research about which objects or functions do what. You don’t need to reason out the setup process yourself, potentially introducing bugs or failures because you missed a detail.
It scales infinitely, and everyone is going to need to start here. Good use of time, worth maintaining.
If you know you want every developer to have an easy snippet they can drop in to try the project, that creates a concrete requirement: tidy abstractions.
Boilerplate increases cognitive load, adding the friction of recall every time someone needs to use your tool. Designing abstractions in a way that limits how much detail needs remembering makes those abstractions easier to use.
Another powerful abstraction is containerized environments. A known-working environment in a can can spare developers tedious setup tasks. Less yak shaving means more conversions.
Until a developer has confidence and a basic mental model of your product, something like raw API docs can be a cognitive load generator. The cleverest projects take some of this sting out through inline customization of their docs, automatically plugging in developer-specific API keys or project-specific column names. This is great stuff.
But before you get to something as concrete as a full listing of your API’s methods, there’s some conceptual work to do. Tutorials are one way to solve this. For many developers, though, even better documentation is actually a working example project showing your stuff in motion, hackable and customizable, with sensible defaults and design patterns.
Other docs that can manage cognitive load: translations of concepts from one domain to another, explaining what’s new in the context of the familiar. Objective-C developers new to Swift craved such content, for example, and it’s worth investigating if you’d like to poach developers from an incumbent.
Beware bad documentation. Poor structure, errata and bad writing can introduce cognitive load penalties instead of benefits.
Combining documentation with an interactive environment is an exciting way to demonstrate value and build adoption. Svelte has a great example of this approach, combining an interactive tutorial with an editing environment that includes a realtime preview. This path to learning gets developers instantly into hello world, while reducing the context switching costs of bouncing between their editor and educational content.
Meanwhile, we need feedback to know when we’re on the right track, or when to course correct. In some cases, automated feedback is essential. In others, automation is impossible.
You need another human to tell you your project is great.
You need another human to tell you your design sucks.
You need another human to give you advice on how to iterate.
A community that can share your journey is an essential component of feedback for many developers, and it requires the challenging work of organizing humans in the beginning. Can’t think of a mega-scale success without this feature.
By contrast, nothing beats a computer at detecting errors in code. The more specific, the more actionable, the more localized, the better. Some projects go as far as including links to ongoing discussions of common errors as part of the error message. Invest heavily in error feedback. Inexplicable errors defeat many developers, and then they exit your funnel.
It’s work to open a thoughtful issue or make a pull request. Feedback from your team here is critical: it shows the project is alive, that the effort is valued, and that the contribution matters. Devs willing to interrogate the guts of your project and propose concrete improvements have serious skin in the game. Reward them and they’ll be better able to use your tools in their project, and more invested in your project as an extension of their accomplishments. These people become your advocates in other projects, in purchasing debates, and the field as a whole.
Hot reloading is now table stakes for all UI development work. Hot reloading automates the feedback cycle. When there’s newly saved content, you get an instant look at the consequences. This is infinitely scalable labor savings, putting more energy into actively using your project than managing tedium like the reload button.
Unit testing can provide similar benefits for logical, under-the-hood work, but this requires making it easy to adopt. Share good example code and build reliable scaffolding to support unit testing in your product to get these benefits.
Clearly, developer flow state is not free.
But achieving flow is sublime. Spend enough time there, and success becomes inevitable. For the developer tools business, flow is the gateway to becoming a trusted and even beloved project dependency. Identify the places where cognitive load is too great, where feedback is infrequent or unhelpful, and you will unlock more flow for more developers, who will make it deeper through your funnel as a consequence.
This is why you invest in DX.