Create SDKs and documentation that tell their own story
When you and your team decide to create a Software Development Kit (SDK), you’re making a conscious choice to take on at least twice the work of a typical engineering team. Think of it like one of those book series that is six novels deep before you think you know all the characters (Spoiler alert: You still don’t know all the characters).
Sure, you’re writing code like everyone else, but your code becomes an essential tool for developers who want a bridge between their product and yours. Oh, and if you think that is where the extra work comes in, it isn’t. The code is the easy part. The hard part is explaining how to use your code to other engineers.
When discussing SDK documentation, have you ever heard, or maybe spoken, a phrase that sounds eerily similar to, “Why bother? The docs will just need to be updated as soon as we write it?” If so, you aren’t alone; nobody here will think poorly of you. SDK documentation frequently gets pushed aside because it takes time and is hard to get right. What if I told you your documentation could become your SDK’s heroic sidekick instead of the villain at the end of your to-do lists.
Chapter 1: writing the first pages
It’s a sunny Monday morning. Your team is raring to go on a new SDK. You’ve got your roadmaps, your goals, and your coffee. The mission is clear: create an SDK that does its job well. As the saying goes, “If you build it, they will come.”
Your team works really hard, and after a flurry of coding and debugging sessions, you release your brand-new SDK to the world! Your feature set is rock solid. You’ve got internal sample applications showing it off to your sales and marketing team and a script that lets them proudly demo your product to customers.
A few weeks later, people start using your SDK and have questions. So they ask for help. Your team tries to answer those questions, and you find out the world has more engineers than your team does, so how do you answer everything? You ask your support team to help and even provide them with answers, but there are SO MANY QUESTIONS that you cannot get anything else done!
You need to change your mission. Create an SDK that not only does its job but also guides others through documentation to achieve their goals as well.
The first draft of your documentation doesn’t need to come after the final line of code. Documentation isn’t an afterthought. It is the guiding star, the narrative that co-evolves with your product. Just like you wouldn’t build a house without a blueprint, you shouldn’t make an SDK without writing and evolving the documentation.
We learned this lesson the hard way. We thought we delivered “good enough” documentation with the release, but it wasn’t. We quickly found ourselves under an avalanche of questions, trying to support customers who we wanted to succeed more than anything, and at times, we were unable to help all of them fast enough. We took an extreme stance for a group of engineers, one I can’t say any team of mine has ever done before in my career—we stopped coding for two weeks and just worked on documentation.
Chapter 2: the saga of review and revamp
A good story never remains static; it grows, changes, and evolves with every telling. Similarly, good documentation is a living entity. Your SDK grows over time: you add new features, deprecate old ones, and make countless improvements. With every change, your documentation needs to evolve as well. And sometimes, it may even need a complete overhaul.
Reevaluating documentation isn’t a one-time affair. It’s a saga, a constant commitment to ensuring your users have the latest, most relevant information they need.
Make documentation a part of your definition of done, a part of your agile sprints, tie it to your release cycles, and integrate it into your team’s workflow. Assign those evaluations to engineers who are experts in that area of the code and, more importantly, those who aren’t. Is your documentation strong enough to support engineers who don’t already have all the answers?
Our code is constantly changing because it will never be perfect, and we will always want to offer more. Our documentation is no different. We look to improve wording where it makes sense and trash it when we find we’re only confusing our readers.
Chapter 3: the chorus of voices
In every epic story, a wise sage advises the hero, helping them along their journey. In our quest for excellent documentation, this sage is your user. Their feedback, experiences, and successes and failures with your SDK provide invaluable wisdom that guides your documentation evolution.
Create channels for users to voice their feedback, from GitHub issues to community forums, from direct emails to surveys. Treat every piece of feedback as a chance to improve, to make your documentation more robust and your SDK more user-friendly. Listen to these wise guides and let their voices resonate in your documentation.
We make it easy to provide feedback and listen to everything, whether positive or negative. Some of our most challenging conversations and harshest critics give us the largest launching pad to something better. We want a “thumbs up” on every one of our guides, and maybe someday we will get there. Until then, we’ll keep our ears and eyes open on you.
Chapter 4: measuring the tale’s impact
The end of a story often comes with reflection and evaluation. Did the hero succeed? Did they learn from their journey? Similarly, it’s crucial to assess the impact of your documentation regularly. Using the right metrics can provide insights into what’s working and what needs improvement.
Look for measures like user engagement, error rates, adoption rates of new features, support tickets related to documentation, and even direct user feedback. Each of these metrics tells a tale, offering crucial insight into how your documentation aids (or hinders) your SDK’s journey in the wild.
Remember when I said we stopped coding for a couple of weeks because we thought that was best for us to support our customers? As soon as we released our revamped documentation, support calls settled down. We began to have the space to work on the product again, build new components of our SDK, and support more customers than we previously thought was possible.
Epilogue: the legacy of a well-documented SDK
SDK documentation is the unspoken hero of the software world. A well-documented SDK not only empowers users to make the most of your product, but it also sends a message. It says, “We care about your experience. We want to provide you with all the tools you need to succeed.”
So, the next time you start your epic quest to create an SDK, remember: write the story early, retell it often, listen to the wisdom of your users, and evaluate the story’s impact.
Your SDK and its documentation are your legacy. Make it a story worth telling that keeps your users coming back for more.
Matt Frizzell is the Director of Engineering for our mobile and in-app teams at Customer.io.
“As both a reader and sometimes author of useful words, I know firsthand how important quality documentation is for our customers, their development teams, and my own teammates.”
Matt savors the daily adventures of life in Boston, MA, alongside his beautifully blended family of five and their unique canine-piranha hybrid.
Our engineering team is always hiring. Check out our open positions!