Faster: Documenting Software in the Age of Agile

As a staff author with Lynda.com, my job is to create training courses for software developers. I’ve been creating and delivering technical content for a long time. The pace of this work has always been fast, but over the past few years it’s become - well, faster.

The Waterfall vs. Agile Development

I was a testing engineer and developer at Borland in the early ‘90s, working on the Paradox and Paradox for Windows teams. Our release schedules then were on an 18-month cycle. Research, specify, design, develop, test and release. Rinse and repeat. This was known as the waterfall model. Each phase of development flowed sequentially, and naturally, to the next.

The first part of a waterfall cycle could be relatively relaxed. The last few months might be a death march, but you knew you’d be able to take a breath after a major release and before the pace quickened again. And the technical writers who were documenting the product had the security of knowing that the software they were describing would remain fundamentally unchanged for at least a year after it was released.

Google, the creator of Android Studio, isn’t alone in this: Apple, Microsoft, Adobe, and many others are also on the agile release train.

For many mass-market and custom business applications, those days are gone. By the time a product with a long development cycle is finally shipped, its original design assumptions may have changed. To solve this and other issues, many organizations have moved to agile development, using the principles of Scrum. Instead of the waterfall, Scrum teams build and deploy features in brief iterations known as sprints.  And where we used to see major releases every year or 2, we now might see significant changes in major software products every quarter, every month, or every week.

A Case Study

Android Studio, a product I use almost daily, was initially released in late 2014. Here’s a list of the product’s “stable” releases through April 2016, as documented on the Android Studio Project site:

1.0 (December 8th, 2014)
1.0.1 (December 12th, 2014)
1.0.2 (December 18th, 2014)
1.1 (February 18th, 2015)
1.2 (April 30th, 2015)
1.2.1.1 (May 12th, 2015)
1.3 (July 29th, 2015)
1.3.1 (August 7th, 2015)
1.4 (September 30th, 2015)
1.4.1 (October 21st, 2015)
1.5 (November 17th, 2015)
1.5.1 (December 3rd, 2015)
2.0 (April 7th, 2016)
2.1 (April 26th, 2016)

Whoa. There have been 14 “stable” releases - product builds that were deemed good enough to be used in production - in less than 18 months. Even if you eliminate the minor point releases (such as 1.3.1), which might only include bug fixes, 8 different versions of the software were released to the public. In just one month, April 2016, there were 2 different stable releases!! Each new version added and removed features, made changes in user interface and behavior, and even made it necessary to reconfigure existing development projects to use the latest IDE and SDK components.

Google, the creator of Android Studio, isn’t alone in this: Apple, Microsoft, Adobe, and many others are also on the agile release train. The software you use today simply won’t be the same tomorrow, and we never know when the next release will appear. How do we keep up?

Users vs. Content Creators

The users (in this case, Android app developers) have mostly become accustomed to this rapid change, but they can also choose whether to accept particular upgrades. (This isn’t true of cloud-based software, where you’re always running whatever is delivered from a server, or mobile apps that are typically upgraded automatically. But for users of desktop software, accepting an upgrade is usually under your control.)

For those who create documentation and training materials about these products, there’s no choice. We have to keep up.

As a software developer, it would be risky to upgrade your development tools just when you’re about to release your own Android app. But there’s nothing forcing Android developers to make the move right away. You can wait until you complete your own deployment cycle, and then look at what’s available in a new tools release.

For those who create documentation and training materials about these products however, there’s no choice. We have to keep up. It’s our job to stay on the bleeding edge. And when the bleeding never stops, you have to rethink how you do that job.

In the “old days”, we’d only write in depth about a software feature when it was almost finished. During the early days of the release cycle, we’d create documentation plans and outlines, but we’d only start to crank out words when the product was at least close to feature complete, and we’d only create screenshots after UI freeze. But if you wait for those milestones in an agile environment, you’ll have trouble making your deadlines. Feature complete in agile means that the software is done for that iteration, that sprint. And when you’re working in sprints of just a few months or weeks, the content creators can find themselves with only days left at the end of the process to create the documentation.

Start Early, Write Fiction, Fix It Later

So the answer is: get comfortable with writing fiction. Start documenting early, and write about what you think the software will be. Then, at the end of the cycle, whether that’s months or weeks, test it and fix it. You’ll find that it’s much faster and easier to repair existing content than it is to create that content from scratch only when you know it’ll be accurate.

In the video training world, we have to be comfortable with creating content that might initially contain some inaccuracies. One of my recent courses, a new version of Android Studio Essential Training, was intended to cover Android Studio 2.0. We had planned to wait until version 2.0 was released to record the course. But that cycle was taking longer than we expected, so we decided to take a leap of faith: I recorded the course with a late beta version of the software.

Android Studio 2.0 was released on April 7, 2016, and because we’d started early we were ready to publish our course just a few days later. Inevitably, a few minor things had changed between the time when I recorded the course and when the software went “stable”. And then, less than 3 weeks later, version 2.1 was released. My “new” course was only a couple of weeks old, and already it was describing an “old” version of the software!

But Lynda.com isn’t bound by the old rules of the technical book publishing industry, with its dead trees and 6-month publication lead times. In the web-based video training environment, I receive constant feedback from my audience who let me know when something in my courses doesn’t match the new reality. I can (and do) re-record individual videos that have been made obsolete by changes in the software. I can (and do) publish responses to frequently asked questions on the Lynda.com web site. In short, by starting early, being comfortable with fixing content as needed, and by using the tools of the web to communicate with our members, I can keep up. We can be agile too.

It Ain’t Changing, So We Have To

The software development industry isn’t going to slow down. Agile development offers competitive advantages that have encouraged software development organizations of all sizes to change how they operate. Creators of training materials who want to offer compelling, accurate, timely content have to change as well. Otherwise we, and our audience, will be left behind.