Documentation Driven Development
Last week I went to Heavybit Dev Guild and learned about designing for developer experience (DX). This was the first time I had heard of the term DX used, but of course it makes perfect sense. All of the Heavybit companies (including CircleCI) are focused around creating developer tools. Naturally when you are creating tools for developers the types of things that make those tools useful and a joy to use are very different than when your primary audience is the mass consumer market.
All of the talks were great, and I am pretty sure that they will be posting videos of the talks here so keep an eye out for that. Three things really stood out to me:
First, during the opening remarks, Jesse Robins talked about how developer tooling changes the culture of an organization. If you want to change the culture of an organization then its not enough to just build a product, you have to also build a movement.
Second, during a Product Discovery Panel, Patrick Malatack mentioned that before Twilio writes a single line of code they write the docs first. We have heard of Test Driven Development, Behavior Driven Development, and * Driven Development, but this is the first that I have heard about “Documentation Driven Development”. This is such an amazing idea that I would love to dig deeper into. So often documentation is just an afterthought. Good documentation (especially when you are working on a FOSS project that does not have “official support”) can make or break your platform. DDD makes a lot of sense when your product is primarily an API like Twilio, I suppose it could fall apart for other types of products. In any case, it is critical to periodically step into the shoes of a brand new user and go through your documentation.
From a support perspective, there is nothing more annoying than getting 100 questions from a user who clearly didn’t even bother to read your documentation. But from a users perspective, there is nothing more annoying than reading documentation and finding out that the person that wrote it has not looked at it in three years because nothing works. In short, if you want your users to RTFM, make sure the FM is worth reading.
Lastly, during a founders panel that discussed building vibrant developer communities. Matt Debergalis talked about how when they first started Meteor they tried to follow an Apple model when it came to product design decisions. He stated that:
Apple Model does not work in FOSS, since you don't control your own product. People are gonna show up with not just feedback, but also code.Overall, this was a great event. I am looking forward to the next one. Huge thanks to HeavyBit for making this happen.
Thank you for reading! Share your thoughts with me on bluesky, mastodon, or via email.
Check out some more stuff to read down below.
Most popular posts this month
- 2024
- Reinstalling Windows at 1am
- SQLite DB Migrations with PRAGMA user_version
- My Custom Miniflux CSS Theme
- How to Disable Wayland in Debian Testing
Recent Favorite Blog Posts
This is a collection of the last 8 posts that I bookmarked.
- Give Your Spouse the Gift of a Couple's Email Domain from mtlynch.io
- Skip the Next iPhone from Articles on Jose M.
- Have smart glasses finally hit an inflection point? from The Torment Nexus
- The McPhee method from the jsomers.net blog
- Pluralistic: LLMs are slot-machines (16 Aug 2025) from Pluralistic: Daily links from Cory Doctorow
- Pluralistic: Bluesky creates the world's weirdest, hardest-to-understand binding arbitration clause (15 Aug 2025) from Pluralistic: Daily links from Cory Doctorow
- Just a Little More Context Bro, I Promise, and It’ll Fix Everything from Jim Nielsen’s Blog
- The Futzing Fraction from Deciphering Glyph
Articles from blogs I follow around the net
Who Is The Sky? by David Byrne
Seeing David Byrne last night for the first-ever performance of Who Is The Sky was one of the best and most impactful concerts/experiences of my life.
via Blog – Brad Frost September 17, 2025Pluralistic: Conspiratorialism's causal chain (17 Sep 2025)
Today's links Conspiratorialism's causal chain: A four-part begat. Hey look at this: Delights to delectate. Object permanence: Legal threats over HDCP leaks; Print your own TSA luggage keys; "A Natural History of Empty Lots." Upcoming appe…
via Pluralistic: Daily links from Cory Doctorow September 17, 2025Theatre Review: Interview (Understudy Performance) ★★★☆☆
One of the best things about London theatre is that once in a while a show will give its understudies a chance to break out of the dressing room and soar on the stage. It's a chance to see talented performers at a discount price. What's not to lik…
via Terence Eden’s Blog September 17, 2025Generated by openring