Have you ever been trying to integrate with a tool, and just kept running into issues and error codes which you can’t find in the documentation? What about having to work on an integration where English is not the developer’s first language, and deciphering the error messages feels like a game of broken telephone? Or, have you had an experience where you followed a tutorial, and a set of documentation and it actually went as smoothly as the writer seemed to expect? These are just some of the different types of developer experience out there, and you can usually tell which product has a person who really understands Dev X.
Building for developers
Building tools and software for developers is hard. Not only are you building for really smart people, you’re building for really lazy people with strong opinions. People who know when you took a shortcut, and who are not afraid to call you out on it. If you’ve ever been served a “something went wrong, error code 401” message from a web page, you know what I mean. We see the message, we recognise the code (401 is unauthorised, or login required), and we facepalm because someone, somewhere, didn’t handle the 401 elegantly. They have just allowed the catch-all handler to step in.
Making matters worse, many developers are happier to complain about things than to fix them. I don’t have time to wade through the thousands of line of your open source project to find this one slightly annoying error and submit a pull request. I don’t want you to tell me “hey you could add that”. I want to complain about it, because it makes me feel better. Oh, also, the more complex systems are really hard to document well. Writing clear instructions on how to set up LetsEncrypt in a helm chart for an open source web service you are trying to self host takes a lot of skill. Mostly because even those who have to do it, do not have to do it frequently.
It turns out writing instructions for something you don’t understand deeply is really hard.
What is even harder than writing documentation, is building a tool so intuitive and easy to use that the documentation is not necessary. A technical tool that is. I’ve never read the documentation for the basic use of any of the various text editors or writing tools I’ve used. Except maybe vim and that’s because its a command line tool built before user interface design was a thing. The documentation and tutorials do exist. There are countless “how to set up scrivener” tutorials out there. There are entire courses on “how to use Microsoft Word like a pro”. I actually might have done part of that when I was at school, but I don’t think it counts. You don’t need a degree to use WhatsApp, or TikTok, or YouTube. Even as a power user. So why is it so difficult to use git well?
Facing up to the gap
An American radio personality, Ira Glass, summed it up better than I could express. And various creative people have quoted, reworked, and reposted the same principle over and over again. Our taste is miles ahead of our skill. If we don’t face up to that gap, if we don’t even try to get through it to a point where we consider our own work “kind of adequate” then we leave our users with nothing.
I am guilty of this too. I know my taste when it comes to writing and art is way ahead of my skill. I am putting in the work, because I have seen what happens when a team overcomes that gap. I have followed tutorials which were written in a way I could follow. I have used tools which make testing safe and easy. If you want my favourite current example, go have a look at Stripe. If you are signed into your account, the examples in the documentation automatically include your test key so you can copy, paste, and go. If, like me, you are building a system where you need to be able to test payments in a non-production environment, they have you covered with sandboxes. All you have to do is use the sandbox key instead of your live key. Only, now I know what good looks like. I can never write documentation which is that complete and easy to use.
Not true. I tell you now, you are capable of far more than you think. You can write helpful documentation. It just takes time, iteration, and debugging. Also collaboration, and accepting feedback and criticism. Almost like writing the documentation is as important as the code, without the feel good moment of watching the tests all pass. It is as critical to the success of your product, as having a product in the first place. If no one knows how to use the thing, then converting from the free-trial phase to the paid-user phase isn’t going to happen.
Okay, maybe you need a product at all first. But you’ve tried to deploy some open source self-hosted solution as a side car to your application, and failed spectacularly because of undocumented “that’s obvious” stuff? That’s where the laziness and the needing to step up comes in. Documenting the hidden complexities in a manner that people can understand. Or, better yet, abstracting them away so that the configuration is actually a whole lot simpler.
Bootstraps and bubblegum
The single most critical part of the developer experience journey is in the bootstrapping, or onboarding phase. Developers are lazy. If getting started with your system is difficult, or expensive, or needs them to contact you, they aren’t going to do it. This is what makes them so good at building really cool stuff that no one ever knew they needed until it was right in front of them. A lazy person looked at a problem, said “I don’t want to do this every day” and so built a tool to do it for them. This also means that if a developer is given the choice of “run this one command and it just works” or “do these three config steps, wish upon a star, and count backwards from a prime number” they will choose the simpler option.
It is so much easier to focus on the bubblegum phase of the developer experience. Once it is all set up and working, you don’t need to worry about it. It is tasty, light weight, and impressive. Low touch. Low maintenance. A good relationship all around. And then something goes wrong, the bubble pops in your face, and you’re left cutting bubblegum out of your hair. A good developer experience assumes that the only time anyone is coming to your documentation is when they’re bootstrapping, or when something has gone wrong. What is the best way to debug error code 143 in a kubernetes deployment that is in a CrashBackoffLoop? What should you do if the system is unresponsive? If you turn it off an on again, is it going to work, or are there going to be consequences?
In these moments, users don’t want to be coming to the documentation. Unless you link it directly in the error message. They want to have an error they can understand. If you have a deployment system where the user cannot watch logs of the container currently being deployed, how are they supposed to debug when it inexplicably freezes for ten minutes? Maybe it is their issue, and they forgot a database migration, but they need to be able to read the logs in real time to debug that efficiently. Error code 143 in kubernetes means something died with a SIGKILL. All the documentation tells you it is a resource limits error. Not enough memory or CPU. It can also be that your startup script is failing before it even gets to the first log line because the DB it is trying to connect to does not have a public IP address (I’ve never done that).
When you have bubblegum on your face and in your hair you are not feeling patient and kind. You want to know what is wrong with the system, and how to fix it, and make it better NOW! When you are trying to start up a new service which you don’t really need any weird config options for, you want to click a couple of buttons, or add a couple of lines to your deployment script. Not spend two days checking the blankspace in your yaml file to make sure the indentation is correct. A good Dev X is built for the times when your patience is at its lowest.
My two cents
Much like ADHD experts will tell you to organise your house to work for you on your bad-brain days. Write your documentation and error messages to be read at 2am by someone who has just been woken up because their production service is offline. Build your bootstrap systems to be idiot proof, because we all know the developers threw the instructions away as soon as they opened the box. Build rails your system runs on, because if you give too much freedom, people are going to get lost.
If someone looks at your rails, and chooses to go off them, you can tell them to RTFM. You will still need to be ready for the response “I did”.
Pippa Hillebrand 