Always be teaching
Crossposted from DX Checkup.
The career of the software developer is a commitment to lifelong learning.
Languages and frameworks come and go. Design patterns go in and out of fashion. New tools emerge that transform workflows, amplifying the yield of developer labor, only to be replaced a decade later with something else.
In short, we must learn constantly or become obsolete.
Which means that building developer tools requires a baked-in commitment to teaching. Every tool has to manage its learning curve, and every tool exists in competition with other tools who will do better or worse at this business imperative.
Making tools learnable
Of course, building the tools gives you an advantage in teaching them: you can adjust the shape of the product such that learning it is less painful. Using existing, familiar approaches is key here: can you extend and enhance an existing way of doing things?
Intuition can be subjective, but if you’re leveraging what people already understand, you’re giving them a shortcut along the learning curve.
A simple example here is an HTTP API. Services ranging from databases to payment processing to ML predictions leverage HTTP APIs because they allow developers on any platform, in any language, to access the underlying power of a product without the burden of also hosting it. This commonality also helps with learning: if you’ve used one HTTP API, you’re going to have some comfort trying a new one. Adhering to common design patterns is essential here: using REST, for example, ensures your product works with existing networking frameworks, as well as existing mental models.
With a familiar baseline in hand, developers need only learn the specifics of your offering and its capabilities, not a whole new way of interacting with your tools in addition.
Peer learning, peer teaching
Core to a successful developer tool is a community that works to teach it on your behalf. This diversification is essential: your team is small relative to the scale of a successful developer base, and you can’t possibly identify and serve every need, every use case, every edge case, every bug’s workaround.
Instead, healthy, sustainable scale requires that you cultivate and maintain a home for the community of developers exploring the edges of what your tool makes possible. This home must be actively managed: toxicity in your core community platform will leak elsewhere, placing a ceiling on your growth and success. It’s not that scary, though. It requires only your active participation, recognizing the success of productive contributors, sharing your plans, and engaging in occasional low-stakes discussion. Acknowledging feedback doesn’t hurt either, and can seriously improve your roadmap.
It’s also important to recognize why people bother to engage in this sort of peer support. It happens when they believe in a project, believe in its power, believe in its ability to uplift their career prospects. Your role in stewarding your community to ensure that the overall cause of your tools acts in service to the developers who invest in you.
Reciprocity is key here: you don’t want to burn out your biggest supporters with repetitious, tedious demands from newbies. So you have to make sure your baseline resources support learning as well.
Beyond API docs
No one wants to read a thick manual about your API, no matter how nicely you style the sidebar and callout boxes. At least, not at first.
Deep consumption of the docs comes later, once you’ve won developers to your way of doing things and they’re convinced to invest more deeply.
Instead, your learning materials should support quick experimentation, validation and de-risking around adopting your tool:
- Basic, copy-pastable boilerplate for a common integration, relieving cognitive load
- Example projects that show your tools in motion, integrated with other common products in your ecosystem
- Brief, easy-to-grasp tutorials geared toward your business success criteria, while aligned with common customer needs
- Recipes and code snippets that are easy to transplant
Where possible, making docs interactive—so developers can experiment and see results as they go—also helps make your case quickly.
Don’t forget your larger context
In Badass: Making Users Awesome, Kathy Sierra argues that it’s not enough to make your developers good at using your tool.
It’s also necessary to understand their goals in the larger context of your tool, and ensure that your learning supports make them better practitioners overall. So if you’re selling payment processing, you want to help developers become better strategists around e-commerce. If you’re selling AI products, some understanding about the theory and mechanics of machine learning is valuable. Remember that today’s weekend hack projects can become tomorrow’s startups.
Help those weekend hackers become more powerful in your tool’s larger context, and you’ll get to ride their success along with them.
