Real Paths Toward Agile Documentation – InApps 2022

How can you foster a culture that gets your developers excited about documentation? How can you foster a culture that gets your developers excited about pleasing their customers? How can documentation become a part of the definition of “Done”? Or is agile documentation just an oxymoron?

These are just some of the questions that pit technical writers and customer success teams against developers, product managers, agile coaches and agile deadlines.

In a nutshell, documentation is deemed uncool and old school. Especially on flat agile teams, there’s a lack of ownership of who’s in charge of docs. And, even worse than testing, software documentation is the biggest hot potato in the software development lifecycle. Nobody wants to take responsibility for it.

Most of all, in the rapid world of agile development, documentation gets put off until the last minute and just ends up endlessly on your backlog. Oh, and of course, there’s not enough money to do it right.

But I’m here to advocate that, for the most part, you’re wrong. There always has to be time for documentation because you should always be developing with your users in mind.

Documenting your software is important because:

• It shows you care about customer experience and developer experience.
• It saves you time and money in customer support by answering repeated questions.
• For API consumers, among other customers, documentation is the most important thing affecting their decision making.
• In a world of microservices and containers, correct documentation increases internal efficiency.
• Documentation first allows you to prototype and build from spec.
• Documentation can lead to better collaboration, which is inherently agile.
• The art of writing documentation lends itself to simpler, cleaner code.

I’d argue that the benefits of good documentation outweigh the cost, time, and procrastination that keeps it from getting done in the first place. Essentially, documentation is just good business sense.

Documentation should fit 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.” — Tony Tam, founder, Swagger API specification (now OpenAPI)

On the other hand, not enough time and money are valid reasons, that’s why today we are going to share real-world examples of the transition to agile documentation.

How WorldPay Went from Waterfall to Agile

WorldPay, a mobile payment competitor of Braintree and Stripe, started out with teams working from four different countries and time zones, collaborating over what became a not very self-explanatory code and APIs. WorldPay Content Strategy Director Stella Crowhurst realized the company could never document everything, so she set out to identify the most important pieces. She followed these steps:

1. Survey customers. What are your pain points?
2. Work with customer service. What pain points are you repeatedly addressing?
3. Following a lean mindset, what wastes were in the current documentation process?
4. Created a gap analysis up against the competition.

Finally, once enough data was gathered, she led two in-house, cross-company workshops: Get to know your user personas and customer journey mapping, working together to answer:

1. Where do our customers need documentation?
2. What kinds of documentation do they want?
3. What are the pain points we want to ease?

From this, Crowhurst came up with a plan to zero in on what they would document and what they wouldn’t.

“We think that if a product is developed the right way, users shouldn’t really need documentation, but in our experience, people usually look at documentation when they have a problem or, as developers, is the tool they use to work on a day-to-day basis to integrate,” Crowhurst said. 

It’s because of these reasons, WorldPay documentation focuses on integrations to support to API consumers and an FAQ to support users when they have problems.

How SendGrid Transformed Kanban with RICE

Communication platform SendGrid’s documentation and open source teams went agile about two years ago. They were using Kanban with two-week sprints but found they were just accumulating a lot of documentation debt. Their documentation was largely reactionary, constantly updating priorities based on other teams’ needs.

“We started out trying to use just a normal agile workflow, sprints every two weeks, and that was about two years ago. What ended up happening is that the documentation was really reactionary to ongoing product release, docs debt, and supporting the support team. We get a lot of requests all over the place,” said Matt Bernier, SendGrid developer experience product manager. 

The team decided they needed to prioritize for business impact. Bernier’s teams discovered the RICE formula on Intercom’s blog:

Reach times Impact times Confidence divided by Effort = RICE prioritization

This simple Excel spreadsheet formula multiplies the number of people it’ll impact by how much with how confident you are in your estimates, all divided by the time and people power it’ll take to complete the task. It prioritizes your kanban backlog for you and solves for urgencies and the total size of the project.

Bernier explained, “Highest RICE score gets top billing — and then gives us the opportunity to communicate with the rest of the business to know priority — number 5 versus 22.”

It took them about half an hour to institute this prioritization system, followed by some tweaks, including adding a due date and business imperative multipliers.

The docs team saw velocity increase by 50 percent in just a month, while the open source team doubled speed in just a week. They no longer had to update priorities constantly, as three lines of Excel did what a Jira backlog could not.

There were positive cultural effects as well. RICE increased transparency throughout SendGrid because everyone knew when their pieces of code were (or were not) to be documented, and why, with the current information at hand, it wasn’t a priority just yet.

Bernier mentioned that it surprised his team that smaller tasks that had been overcooking on the back burner would rise to the top as the formula revealed them as quick and inexpensive. For the SendGrid docs teams, they were able to have a greater sense of accomplishment as more things were done.

Much of this article has been adapted from this talk I gave at the Aginext Conference in London, May 2017.

Feature image by Tyler Lastovich via Unsplash.