Some thoughts on developer documentation I’ve shared in recent interviews: We need more narrative example cases in our docsets, because so many docs poorly serve onboarding developers.
The core problem: Every developer brings random assumptions and past issues to new API experiences. If you don’t help onboarding devs learn how to conceptualize your system, they’ll burn from the cognitive friction of trying to apply their assumptions to your reality.
And yes, with enough brute force, you can smash a square peg into a round hole. But you’ll get more adoption—and with more positive energy—if you say “hey fellow developer, we use round holes here.”
How I tackle this problem: I find educational opportunities through some detailed or obscure use cases. The basic framework:
* Come up with a unusual use case that has around 5 steps. That’s enough to show how to frame the way different calls or components interact, any complexities in fields submitted or consumed, or other side considerations without turning the doc into a novel.
* Consider the audience as being on the more inexperienced end of the spectrum. Don’t get into explaining college clas fundamentations, but beyond that don’t assume knowledge. If your audience is more specific than “anyone who might get hired to write code for a client,” use that as your experience metric and still target the inexperienced end.
* When describing each step, write a little about the thought process. Link them together as a single coherent narrative. Be to the point—these aren’t recipe blogs—but put a little more effort than having each step amount to “Then call the getStuff method.”
* Leave intentional voids for curious devs to explore. That could be a branching error handling, calling and corelating more related data, allowing for UX improvements, etc. Call such topics out as out of scope, and do so knowing some devs will chew on those as thought prompts during coffee breaks, commutes, etc.
* Finally, make the purpose of the article clear: it’s in the spirit of onboarding, not as ready-to-use code. State it out right or let it be implied, depending on your informtion architecture. I mention this last to use everything above as context, but this purpose should be at the top of the document.
That said, this is just one tactic to use. A great dev site also has ready-to-use code for routine operations. A great site contains detailed information for each endpoint, data model, etc. so reference and feature exploration. A great dev site is searchable, but via a search engine and within indiviudal pages. But those features don’t address head-on the needs of onboarding devs to learn what mindset to get into. Narrative example cases do.
To show this idea in action, here’s one of my work samples. It uses a fictional disease analysis product based very loosely on a past project.
Originally published on LinkedIn in April 2023, revised September 2023