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.
Cognitive load
There are so many ways to manage cognitive load, and they’re relevant at different stages of the developer journey.
Onboarding optimization
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.
Designing abstractions
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.
Docs
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.
Interactive learning
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.
LLMs
LLMs do an incredible job of managing cognitive load for languages and concepts that have significant history. Getting help from an LLM on C++, CSS, or JavaScript borders on the science fiction. Beware application of LLMs for more novel technologies, as their so-called hallucinations introduce cognitive load landmines for less experienced developers. Still, in many cases they can be more effective than compilers and related tooling at discovering syntacical screwups and other broken structures.
Feedback
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.
Successes
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.
Errors
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.
Collaboration
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.
Iteration
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.
Flow
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.
