Jennifer Rondeau on the mix of grammar and tech in API documentation
/
Jennifer Rondeau is a technical writing manager at Capital One, on the API design team. Dubbed by Jason Harmon as a "Golden Unicorn," Jennifer is a long-time advocate of the power of API documentation.
We see it time and again. When developers are asked what is the most important part of their API decision-making process, API documentation tops the list. In fact, it’s considered an incredibly valuable part of the overall developer experience or DX. And pretty much every application programming interface [API]—at least the public ones—have some sort of documentation. Yet the quest for the elusive perfect API documentation is a continuous one, particularly when it’s not a priority in the development process. Today we talk to one of Capital One’s technical writing managers Jennifer Rondeau to learn first-hand how you can make documentation a part of a DX-first world and to learn why she thinks documentation planning should be at the table along with the rest of your API strategy.
The API Economist: To start off, tell us about your experience in the API economy and as a technical writer.
Jennifer Rondeau: I’ve been writing software technical documentation for 13 years. Before that, I was an academic in a totally different field, but I wrote from pretty early on in text editors—including vi on a VAX, way back in the day—and I was part of early efforts to put research and teaching materials online, so I’ve been interested in software tools and development for much longer. And as it turns out, teaching and research are fundamental skills in software docs. There’s a nice piece in Techwr-l [technical writer magazine] about how a good technical writer is always a good researcher and I think it nails a skill that is often not understood by stakeholders in development.
Once I started documenting software, it didn’t take very long for me to get interested in code documentation. Here, if a writer is involved, it’s often at the level of the API. My gateway drug was actually writing API documentation for classic Java interfaces—editing Javadoc comment blocks, filling in all the TODOs that programmers left behind, and putting together the big picture of a set of Java APIs.
Then I did a stint as what Microsoft used to call a Programmer Editor in the Games group, editing API docs for the Xbox SDK [software development kit], and really my job was to clean up style, but you can’t be a decent technical editor without understanding what you’re editing. You need to understand which words to change and which ones don’t work in a technical sense. And for reasons that remain a bit mysterious to me, I fell in love with pretty low-level code this way—pixel shaders, bit flipping in C and C++, that kind of thing. I couldn’t write the stuff—that came later—but I could read and understand it and I was fascinated by it.
That contract ended, I returned to the world of documenting GUI-based applications, and by 2011, I was ready to leave the world of software altogether. But then a project came along at Symantec, that sucked me right back in. It was a set of SOAP APIs and I got to take the documentation side of it and run with it. It was an amazing team, with a brilliant group—dev lead, QA lead, PM [product manager]—who really encouraged me to learn new things and contribute in a lot of different ways. I ended up owning the whole doc set, the code samples, Javadoc comments and build, [and] the OAuth docs. I’ve wound up writing a fair amount about OAuth because, once you understand it, it’s great, but it turns out that it takes a lot to learn OAuth well.
At what point in the development process should you start writing API documentation? What role/s should be in charge of writing API documentation?
I think it’s the wrong question. When you ask a question like this, people assume that there’s a point where you start writing—some time well after project planning and kickoff—and you don’t need to worry about the documentation before that. But you do need to think about it from the very beginning. If you bother to hire a writer, bring them in at the start of the project. If you don’t hire a writer, you still need to consider docs from the start of the project, and in that case you need to think about whose responsibility the docs will be and how much of their time docs will take. The most important thing isn’t the job title, but it’s that the person who is in charge of docs is sitting down at the table at the start.
And that’s not just API documentation. I’ve yet to work on a project when a project manager or technology manager doesn’t say at some early point, ‘We’re not ready for docs yet.’ Inevitably then what happens—when the people who have to deal with the words are brought in late—is that a lot of rework has to happen unnecessarily. You were ready for docs months ago—if you hired me, you were ready for me—and you just didn’t know it.
Not everybody can afford to hire a dedicated writer, or maybe a better way to put it is that too many folks don’t understand the ROI [return on investment] of hiring a dedicated writer. So I prefer to think of the question in terms of allocating resources to documentation. It can’t be a side project. It can’t be something extra. Documentation is not decoration. You can’t put good documentation out there unless you think about it. You can’t use it as a wrapper. Eventually you can get good documentation out of any process but it’s not as effective or efficient as if you put it on the table along with all the other components at the beginning.
There’s a lot of extra explanation and testing that has to happen if you think about documentation after product development is underway. Often whoever’s working on the docs is one of the few advocates for the customer, the external user of the API. This is especially true with a project where you’re opening up APIs for external consumption that were originally written for internal use. People get used to certain ways of doing things, insider-speak. If it’s hard to translate that insider-speak for the docs, for example, maybe the best thing to do is rethink the API itself. But if you wait for documentation, it can be too late, or if you realize you really have to go back, it’s more effort, time and resources wasted.
Jennifer Rondeau giving a talk at APIStrat 2015.
What are the essential parts or sections in a developer-friendly API documentation?
There are two things that really matter: Complete and accurate reference documentation and working examples. And I’d probably put working examples ahead. In my limited experience, developers go to the examples [first]—you just want to get something working. At Symantec, If our examples didn’t work, our customers would pick up the phone and call support. I would always put comments in the examples because if that content was going to get read, that’s where it’s going to get noticed. The point is working code. Don’t tell. Show.
And yeah if you want to do something complicated with the API, or if the API itself is either complicated or badly designed, you're going to need the reference documentation.
People expect other things, too—tutorials, and you need Getting Started guides, how to get API keys and OAuth flow, rate limits. These are essential too.
Should multinationals have translators for API documentation?
I think that really depends because English is so much the international language of software development, so I don’t think localization is as big a deal as it might have been once upon a time. But, that being said, it’s pretty important to write with an awareness of a global audience which allows itself for easier translation—using global English [cross-cultural English, not slang and not very formal English.] And I think that reliance on automated tooling usually produces bot-like documentation, but, if you write global English—short declarative sentences, keep it in the present tense—or future tense because programmers are used to it—but keep it consistent, avoid complex sentences, it can ease the need for translation.
Also good localization is very expensive. And ROI is difficult to measure.
Which documentation parts can or should be automated today?
Reference documentation certainly. The thing about Swagger and RAML and API Blueprint, you [want to get your] reference documentation out of your API definition file, somehow. As long as you’ve got tests in place to make sure your implementation matches your design, automating at least your stub makes sense.
One automation workflow that I’m a really big fan of that’s Swagger-specific is a pair of open source tools, Swagger2Markup which exports your Swagger definition to either Markdown or AsciiDoc, [which are] plain-text markup languages. There’s a similar tool for RAML, and the folks at Apiary have done nice things for API Blueprint and for Swagger. I want to say here that I really recommend AsciiDoc over Markdown. That’s a whole other discussion, but my main point is that AsciiDoc is cleaner out of the gate, and then down the road when you need more things than you realized at the start, it’s more scalable and more easily extensible. So then you’d use Asciidoctor to get your HTML out of your AsciiDoc markup.
But back to automating reference docs: The point is that you want to start from your API definition, which works whether you write it first and then code to it, or generate it from the code. Some folks pretty much stick with the auto-generated content, but at Capital One we start with the definition file, export it to a markup file where the writers can edit descriptions and generally provide a level of detail that’s not possible in the definition itself, and then put it together with the rest of the doc components—authorization, code examples, using our platform—and build into HTML. If you just generate from your definition and don’t bother with any human intervention, unless your API is dead simple, chances are the content won’t be adequate.
People have also customized tools originally meant for classic interfaces—REST Doclets for the Javadoc Tool, for example. But you can also integrate your docs with your tests—Python has doctests that you can run against test or example code, and there’s a Spring tool, Spring REST Docs, that includes a documentation method as part of Spring’s mockMVC tests. The basic idea is that if your docs fail, your tests fail, and your build fails. So you have to keep the docs up to date. That’s another great approach, and in the ideal world we’d automate from the API definition and from the tests. We’re not there yet, but some of us are working on it!
How does documentation fit into the overall API design process?
Well, as I’ve already said, at the beginning! But that’s the when. The how depends on the rest of the design and development process. But no matter what, you should couple your docs as tightly as possible to your API definition and to your tests. This isn’t necessarily easy or obvious—we don’t have a complete toolchain for this kind of approach, only pieces of it if we want to couple to both definition and to test. There are tools to do either, but they don’t integrate [or] haven’t been integrated, [leaving] a lot of folks still write reference docs by hand. But writing by hand is a good way to let documentation get out of sync with the API pretty quickly as you iterate over versions.
If you include documentation as part of your planning from the beginning, then you can explore what it means to explain the API to external developers as you’re designing it. And as I said, if it’s hard to explain, maybe you should rethink the design. Rethinking can be as simple as cleaning up names to be more intuitive and self-explanatory, or it can be complex—how a set of body properties is architected, for example, or how multiple request objects relate to each other.
What are the biggest mistakes people make in API documentation?
Not making assumptions and prerequisites clear. Not giving a clear sense of the workflow.
I think a really common mistake is to assume that you are like your audience. Even if you’re a programmer writing documentation, if you assume that the programmer reading it is just like you, you’ve probably lost your audience. Especially if you wrote the API, you know so much about how it works and what’s going on under the hood that it’s almost inevitable you’ll miss important bits because you forgot that not everybody knows all the things that you do.
OAuth is a big stumbling block for programmers. Most APIs these days use at least one of its flows for authorization and access control. How people document it is all over the map. [The following to things need] to be way up at the top [of your API documentation]:
- Here is what you’ve got to do to get started. This includes getting an OAuth access token, and ideally—although this could be debatable—some recommendations about security best practices related to managing the OAuth bits.
- Here is how to call our API.
Organization—what writers sometimes call information architecture—is really important and often not given enough attention in API documentation. Good, clean, well-organized content helps with discoverability and makes it so much easier to get started.
What will the API economy look like in five years?
It seems to me that we’re heading pretty fast in the direction of hypermedia. The other place of course is the Internet of Things, which I frankly find less interesting. The API side of it doesn't seem as interesting. I do think banking and fintech is likely to get more interesting in the API space. Another place is health management, also government, which is pretty exciting. If you combine the federal government’s move toward open data and open source with the notion of the citizen developer, and you add what Kristof van Tomme calls an open GUI for the API Web, it’s putting the power of coding in the hands of more and more people, and making more and more information available programmatically to all of us. The more that programming skills are distributed, the more programming is demystified and people can see by example how they can learn because we show them with APIs, the more opportunities we can open up for all sorts of things. I know, that’s a pretty utopian vision, but I cherish it!
What should developers be doing to prepare for the future of the API economy?
Thinking more about their users, thinking about real people because that to me is where you start with design. Even if you’re just fixing code, you can still think about how that bug fits into the bigger picture. And that bigger picture does inspire API development even more.
Community involvement is tremendously important—there’s a big API community that is extraordinarily welcoming and friendly and open. These people are real models of openness and helpfulness to the rest of us—Kin Lane and Mike Amundsen were gods to me two years ago, and then I show up and I’m interested and I want to learn and these people want to hear from me.
What are your three favorite apps? (Not the ones you like the most, the ones you really use the most.)
Define app? Seriously, I think of different kinds of software differently. Is this the kind of thing you mean: Slack, Twitter, Sublime? My top apps are an at-the-moment thing. Although Slack and Twitter have been near the top for a while now. Twitter is my gateway drug, it’s where I get links to so much of my other stuff. If not for Twitter, I wouldn't have been at APIStrat. [It’s] how I learn about these resources. And Slack just keeps me connected to so many communities. I moved across the country last Fall, but I’m part of communities elsewhere that make it seem almost like I’m not gone.
Who is the must-follow, undercover API expert on Twitter?
Arnaud Lauret @apihandyman or Zdenek Nemec @zdne at Apiary—these are the folks who most inspire me lately. Another great API resource and community is London’s Write the Doc Meetup.
I think that Brad Fults @h3h and James Higginbotham @launchany have both covered developer-friendly API documentation fantastically. They are both brilliant and they cover the important things in a thorough but compelling way.
Have more questions on the best API documentation or want to share your thoughts? Go ahead and comment below or tweet it to us at @APIEconomist and Jennifer @bradamante!
