Writing the docs in the Agile era

The key to success in an Agile environment is to get involved - in every way you can and as early in the process as possible. Here Tom talks about what this means for tech writers.

Written by Thomas Boumil
06 October 2020

I worked for many years in companies using Waterfall development. At the time, it was the only game in town. For the last 12 years, however, I have worked in an Agile house and after some difficulty changing my mindset, find I prefer it. Technical writing in an Agile development environment creates some difficulties for writers, but also many opportunities.

Background - Waterfall versus Agile

In the early part of this century, a new development methodology began to gain favor - the Agile methodology. Until then, virtually every company producing software used Waterfall development.

I'm sure most of you remember, or at least heard of Waterfall development. This model for software development involved long development cycles, usually six months, but sometimes longer. Each cycle began with Product coming up with an idea for a new product, or an improvement/expansion of an existing offering and writing a detailed requirements document. After concept approval, the engineering department would pick-up the requirements document and begin designing a solution, ultimately generating a detailed design document. Next, the actual development would occur, followed by testing the software and fixing bugs.

There were numerous problems with this style of development, including slow introduction of products, difficulty in modifying requirements, and minimal feedback from end users until after delivery.

Agile development works differently. First, there are no detailed requirement documents produced. Product managers/owners work directly with the developers to hash out the ideas and break them down into small incremental deliveries. You can think of this as features being broken down into user stories, which are then broken down into smaller tasks. The creation of user stories and tasks fills the same niche as requirements and design documents in waterfall.

Small teams work these tasks and user stories, delivering incremental code in each sprint (usually every two weeks). QA testing occurs in parallel with the development. Most often the goal is to deliver an MVP (minimum viable product) quickly. The Agile methodology results is smaller efforts, faster time to market, faster feedback from end users, as well as the ability to quickly change direction if dictated by the market.

All in all, there is considerably less waste or potential waste and faster ROI.

What Agile means for technical writers

As I said, I had a little difficulty at first adapting to Agile. I remember starting at my new job and immediately hearing about a new feature we were developing that required a fairy large piece of documentation.

I figured, "OK, no problem. When are we delivering it?", I asked. I was told it would be available in four weeks.

"What," I thought, "Can you tell me where I can find the requirement or design docs?" The reply came, "Oh, we don't use those. Go look-up the user stories under the feature. Those will tell you everything you need to know."

Well, the user stories did tell me quite a bit, but not everything. Extra effort was required. If I was going to write effectively in this environment, I was going to have to integrate myself into the product and development teams much more closely than I ever did in waterfall.

The days of being spoon fed information in specification documents were over.

How I got going

One of the first things I did was to ask for an invite to the daily engineering team's stand-up meeting. These meeting usually last 15-30 minutes and allows each engineer to state what they did yesterday and what they are planning for today.

While I typically did not attend these meetings daily, I went at least once per week and more often if I had questions, or in some cases comments. This allowed me to not only get a deeper dive into what was happening in development at any given time, but also to become a contributing team member, even if I wasn't coding. As an added benefit, gaining a deeper familiarity with the team members, allowed me to have questions answered more quickly and my docs reviewed in a timely manner.

I wasn't some unknown tech writer that came and bothered them when they were busy. I was a team member that was in the trenches with them.

I also began participating in CFTs (cross functional teams). I honestly don't know if every company uses CFTs, but if they don't, they should. While not strictly a part of agile, CFTs are a gathering of representatives from each stake-holding group (Product, Tech Pubs, Marketing, Development, Implementation, Customer Service, etc.).

At these meetings we would discuss everything from determining beta testing candidates, to launch collateral, to likely next steps. We also had the opportunity to voice any concerns or perceived problems and work toward a resolution.

Some final refinements

Everything I mentioned above provided a good start, but over time, I saw that I needed to do a few more things.

One important item was to participate in PI (program increment) planning. These are meetings of all development teams on a particular platform or epic, to plan what they are committing to developing over the next 12 weeks, in six sets of two-week sprints. This is when many of the user stories are written.

Being an active participant allowed me to be in on the ground floor of the development effort and gave me greater insight into the product goals and how/when those goals were to be reached.

Over time I also decided that, for many features, I needed to have my own user stories added to the project and tied to the appropriate development effort. I also discovered that a fair amount of planning and effort sizing takes place prior to the PI. Seeing early roadmaps and sizing WAGs allowed me to better plan my own effort and that of my department.

The key to success in an Agile environment is to get involved - in every way you can and as early in the process as possible. The days of having months to read and review specification is long past. The new world of rapid development is here and far superior, if you embrace it.