Automation Is the Key for Agile API Documentation – InApps 2022

The very idea of documentation often invokes yawns followed by images of old-school, top-down Waterfall project management. Documentation is often seen as an albatross to an agile project management process built with rapid iterations, learning from customers, and pivoting.

Yet, particularly with the API space, the most important thing that developers are considering is the documentation.

But how can the all-important documentation be integrated into the agile world without slowing it down? I’ll share some wisdom from pro-documentation agilists that I spoke to in the process of writing “The State of API Documentation” white paper for the APIDays conference series, in order to help understand what’s holding us back and how to move forward with agile documentation.

For the sake of this article, we are focusing specifically on API documentation in an agile environment, but the lessons can be applied to just about any agile team.

Why Can’t Documentation Be a Part of Agile?

Some would say that this is the consequence of culture or perhaps of a lack of ownership.

“API design-first is inherently not agile. We design the whole thing and then throw the whole thing over [declaring] ‘Be the recipients of our wisdom’,” quipped Emmanuel Paraskakis, head of product development at APIary (currently being acquired by Oracle).

Even though DevOps are fighting to break down these silos, there’s no doubt that documentation, like testing, continues to be a hot potato thrown around IT departments. It’s not something that’s deemed fun and, despite all evidence to the contrary, it’s not something deemed important.

“In the end, if it’s done without control, we will have many many microservices that don’t speak the same language and it will cost a bunch of money.” — Arnaud Lauret, API Handyman

Andrew Davis, founder of tech writer agency SynergisTech, said, “The piece about it being ‘the number-one thing people want’ isn’t registering at most companies I serve. Not all of them are in the open-source space, where documentation truly sells the product, but most of my clients think about documentation too late and resist paying respectable rates when they find the rare combination of developer skills and technical writing talent.”

There’s no doubt that while time and time again documentation is lauded as a huge factor in decision-making, it’s brushed off as unimportant, particularly on agile teams.

One problem may be that, in most agile situations, project milestones have just been replaced by story point estimations, that still have devs and teams blocking off time limits, further restricting the development process in a way that then creates new excuses to pass on the documentation.

As Arnaud Lauret from API Handyman put it, “This is the good and bad side of agile autonomy.” You are faster, more efficient, and have a greater capability to meet customer expectations, “but, in the end, if it’s done without control, we will have many many microservices that don’t speak the same language and it will cost a bunch of money.”

Nonetheless, API documentation should fit perfectly in the agile world “because you have the ability to modify the thing that drives the whole process at almost every stage of development. And the modifications can affect in a controlled way all of the artifacts that are downstream of it,” said Tony Tam, creator of the Swagger’s API framework. 

Tam explained that successful API documentation is “not a Waterfall process at all because it’s not a serial thing. The client, the documentation, and the server all happen in parallel in the design changes.”

As Davis alluded to, documentation is only seen as useful in some open source situations, where you want to cut down on preventable tech support calls. But certainly, as we give developers more independence to work with microservices, containers and other smaller pieces of code in varying languages, we have a greater demand for documentation on internal teams too.

In fact, since agile sees internal teams processing code so quickly, it might be even more important for them to document as they go.

As an API consultant, Rich Visotcky found that the documentation he needed to create for his clients in the construction industry would be substantial. There could be six or seven application teams plus two other service teams that had to consume it all.

“Updated, useful and concise documentation was very important for these teams to consume our services, especially as they changed sprint after sprint after sprint,” each of which lasted between two and three weeks, he said.

This meant they couldn’t just have a wiki or an API manual that needed constant updating, so they went ahead and worked to create an API that was as self-described as possible.

Like all things in the agile space, automation plays a crucial role in keeping documentation up to date.

Can Definition Languages Make Documentation Agile?

Or perhaps a better question is: Can API definition languages, such as Swagger, sell documentation to agilists? 

“One of the things that we quickly realized we couldn’t do was create documentation that lived apart from our code. It had to live directly alongside our code or it’d be immediately out of date,” Visotcky said.

To accomplish this, he used a combination of XML comments that got generated by the actual method signature, a Visual Studio extension for documentation called GhostDocs, and then they used the XML documentation to generate Swagger API documentation, which he says kept the documentation and code intrinsically linked.

“Swagger was awesome,” he said. “That gave us some short blurbs that people could pull up on our website released internally.”

Paraskakis echoes this need for automation, adding that it gets the consumers involved early and often.

With APIary’s definition language API Blueprint “Not only are we going to involve you as a consumer, we’ll give you a live prototype in the form of a code server. You don’t have to wait for the sprint to be up or the release.”

Prototyping is, of course, a way to test things out in the agile development process without having to build too much in advance. In addition, this process allows for automatically driven tests, “so we assure this contract [between API provider and consumer] won’t be broken.”

Paraskakis continued, “A lot of people talk about the lifecycle where you create it, then the documentation, etcetera. Then we want to go back and do more things once we get feedback. Maybe it’s microservices, use cases or partner APIs, but you reach a point when you need a lot of APIs.”

That’s when Paraskakis advocates for a style guide, a lot of it expressed as a document. “You need to have tooling that takes the style guides, introspects it, and advises you at the point when you are straying from the style — not that prevents you from deviating but alerts you.”

“You also need integration with your version control system so you can manage changes, branching, pull requests, merging, especially when you bring in collaborators from the outside,” allowing them to make a suggestion in a different branch.

Uri Sarid, Chief Technology Officer of Mulesoft and co-creator of the RAML API description language, described agile as “the ability to go fast and then change.”

It’s for this that Spotify uses RAML for front-end and Mulesoft for backend integration. What’s the secret to the music giant’s agile success?

“If you want to go fast, you actually need to specify just the API — it’s about just tight enough coupling and to know what doesn’t change. APIs tell you exactly what you rely on. Good fences make good neighbors. The API economy has evolved on loose coupling.”

Sarid offered Docker as another example because they have a well-defined API that is very specific about what you can do with it.

“If you don’t do it, it doesn’t work. To be fast you need that exact contract. Because all containers on a freight ship are exactly same, they all need that contract.”

Basically, Sarid is putting up documentation as a very important part of that contract between API exposers and API consumers. 

We never allow something to be shipped that hasn’t been documented, making sure the documentation iterates along the way as the product develops” –Romain Huet, Stripe.

“The more microservices you have, the more agility you need, the more important it is to define the contract so you know what won’t change and what will change.”

Netflix, famous for its so-called Chaos Engineering, actually uses automation and documentation to create harmony for its mostly internal APIs.

Sarid pointed to how their code embodies their APIs in both human and machine-readable terms. And when a bug has been discovered, it’s because someone had miscoded, showing a need for some more auto-generation.

No Excuses

There’s a strong argument for an internal or external tech writer to join the agile team and take charge of the API documentation. And yes that’s useful for curating it all. But perhaps it’s more important to have each developer be responsible to document her or his own piece, before allowing for its curation.

As long-time technical writer James Neiman argues, documentation efforts should be aligned with product release cycles.

“If you are embedded with a product and engineering team, in the agile environment, the definition of ‘Done’ is that the docs are updated. It can’t be Done without.”

Of course, this is harder when a project progresses. The Scrum Master or Product Owner needs to help the team outline an agreed upon definition of “Done” from the start, which should, just like testing, include documenting.

“What’s critical is to start documentation early on in the process and make sure it is continually updated,” said Romain Huet, from Stripe’s developer relations team. “We never allow something to be shipped that hasn’t been documented, making sure the documentation iterates along the way as the product develops.”

He went on to say that this is a really great way to see how the developer experience will look like before it’s even published because, even when you are interacting on shorter, more agile development cycles, you want to make sure that developer experience is paramount.”

Huet also reminds us that the easiest way to create simple documentation that’s kept up to date is by keeping your code simple. Stripe recently realized that when integrating the payment tool via Apple Pay, where they reduced down to a simple line of code. This isn’t new either. Stripe was created in 2010 around the simple principle that “It should be easy to set up and accept payments,” which is why the Stripe API enables this with only 14 lines of code.

By writing the documentation spec up front, you can be more agile by planning out the “ideal code” ahead, which in turn has us thinking about what the developers would like to write and, as Huet said, a delightful way for them to integrate.

On Visotcky’s agile team, they too found success when documentation was incorporated into the process.

“Whoever wrote the code updated our documentation. It was part of our definition of Done.” Visotcky went on to explain that “We checked it as the team. The person who was updating the API or updating the endpoints or changing the way it behaves probably had the most to update the documentation, but we checked it as a team to update the behavior of what’s actually going on in the API.”

In the end, Visotcky said they had two types of documentation, what he calls “collaborative” or what their customers were asking for and Swagger which was generated for their own use. They continued to write and maintain the docs for their own needs, constantly trying to minimize it all.

What matters is that you have API documentation, but, like all things agile, how you do it should be customized per customer, per product and per need.

Feature image via Pixabay.

InApps is a wholly owned subsidiary of Insight Partners, an investor in the following companies mentioned in this article: Docker.