Developing a Great API Requires Great Technical Writing
As a Product Manager, I want to build great products so that customers’ lives are improved. Rather lofty user story, right? Its acceptance criteria seems fairly straightforward.
- Have a great engineering team.
- Have a well-thought-out business objective for the product.
- Understand your customers’ needs.
- Create a technical design that is feasible, viable and desirable.
- Build the product in a way that scales so you can continue improving your product rather than maintaining its infrastructure.
- The list continues…
There are dozens of books dedicated to the pursuit of building great products. Ultimately, if you’re building an API product, sound technical writing can be the key success criteria to ensure that external developers can leverage the full value of your product. While technical writers may not be coding alongside your engineering team, they can help ensure the code your team produces works as envisioned. In this capacity, they’re a fully integrated, and essential, partner in your APIs development.
As an agile API development team continues down the path towards production, there are likely to be small changes made to maximize usability and business value for the product. This is where strong technical writing becomes a key differentiator between a good product and a phenomenal product. No doubt that each PUT, POST, GET operation of your API was strategized and thought out — but a major detriment to a team’s time when building an API product can be constant emails, phone calls and meetings with other teams.
“How does this PUT operation work?” “What’s required for this POST to return the value I am looking for?” “Why is this field encrypted?” “How do I decrypt that?”
Now imagine getting these questions from external developers trying to integrate with your API? How many questions do you think they’d pose before giving up and partnering with someone else’s API?
Here at Capital One, we have a deep commitment to creating quality APIs for both internal and external users. Within the company, our teams can leverage a cadre of resources and tools to ensure they’re building APIs that meet our quality standards. We have a Design Review Board (DRB) to evaluate API architecture and how it connects to the enterprise. We have a Design Experience (DX) Review process to help guide and focus understanding of our product and its potential. And we have an API Center of Excellence that ensures that we are enabling developer success through the co-evolution of our processes and standards
These resources are meant to help teams select the right patterns and existing systems to ensure their APIs do what they’re intended to do — all while leaving some room for them to grow and evolve.
Aside from these resources and tools, one of the greatest assets in our quest for creating quality APIs are the technical writers assigned to our APIs. Earlier this year, I joined the in-progress effort to create an API related to data organization and access. The idea had evolved before I joined the team, and continued to evolve afterwards, becoming quite complex in scope.
Our tech writing team, run by Kyle Dallaire and Cheyenna Duggan, helped test my API by playing the role of external user and asking product questions before we’d started putting down code, let alone hit market. During one early team meeting, the question of what an “asset” was came up. We were building an API product around digital data — which we were calling “assets” — but hadn’t stopped to define the term or how it functioned within the API. Another question from an early meeting involved the providence of assets being posted — how do we know an asset and an account belong to one another — leading to the addition of an owner ID field.
Sometimes complications get worked in that only make sense to those that are close to the problem. Anybody coming in cold and asking questions about how things work helps the product and engineering teams stop and go, “Did we build this right?” Both these items would have been caught in testing; however, catching them at the design spec phase, before the code was even done, greatly benefited both our timeline and final product.
The technical writing team also helped the product team articulate how the product worked and what a developer could do with the API. This helped uncover value to improve upon our design and approach to integrating existing APIs. With my role focused on the different stakeholders, maintaining timelines, and delivering a wonderful user experience, it was invaluable to have someone else coordinate with the engineering team and take a fine-tooth comb to the API spec. Having the technical writers focused on making sure someone outside Capital One could understand how our API was written, and the potential ways it could be used, was absolutely critical.
With technical writers who understood the API almost as well as the engineers, I didn’t have to stress out about understanding the minute details of the API spec and how it related to the usability of our API and documentation. This division of roles and expertise allowed me to focus on the strategy and next steps for our product.
I’ve been a systems technician, a developer, a strategic consultant, and a product manager and have worked with technical writers in some capacity throughout my entire career. I cannot imagine an agile API development team that didn’t include technical writers.
As a product team moves towards the final stretch of pushing an API to production, remember that your users don’t just want to know if an API works as intended, they want to know how it works as well. A skilled, savvy, and empowered technical writing team can help you better explain your product and unlock its true potential.
DISCLOSURE STATEMENT: These opinions are those of the author. Unless noted otherwise in this post, Capital One is not affiliated with, nor is it endorsed by, any of the companies mentioned. All trademarks and other intellectual property used or displayed are the ownership of their respective owners. This article is © 2018 Capital One.
