Incrementally updating documentation, like a product
Backstory of the problems, open questions, and resolutions of transitioning to iterative documentation
Transitioning from waterfall development to Agile was an experience in itself in my previous organization. To the average person on my product team, it seemed like an impossible goal to take such huge complex products with hundreds of moving parts and break them down into units that we could build iteratively. The technical writer was equally baffled about how to transition from writing entire guides, to just making updates for the features of the sprint, especially in such short cycles. My product team, Project Portfolio Management, was chosen to be the trail blazer for this incomprehensible task. We began ‘sprinting’ and meeting as scrum teams. Technical writers would need to be part of the scrum if they had to deliver updated help so quickly. Engineers, who were the scrum masters, wondered why technical writers were needed in scrums. Why invite unnecessary people and distract the focus from technical discussions?
Technical writers had to present their case. If they were not involved early in the design, then it would be too late by to turn around deliverables so quickly in short sprints. It was impossible to effectively review 20 strings and 50 messages the day before code check in and improve their usefulness to end users. Additionally, how could technical writers complete detailed design documents and also have them reviewed by the entire scrum team, who now would have no time for detailed reviews?
To better understand how to grow in Agile development, we started a book club. The book that got the ball rolling was The Connected Company by Dave Gray. I still have memories of how the succinct and action-oriented advice in this book helped us over the more traditional Agile books back then.
Beginning in 2012, we started sprinting and products started having ‘scrum meetings’. Product managers barely had time to get their designs complete. Technical writers worked to review the product designs quickly, turnaround string and message reviews, created quick help designs, and sent them to the scrum team for a quick review. This was a lot to do and over time, we just fell behind. What made it worse was when some old patterns crept in. Unplanned changes to the design in the middle of the sprint became frequent. This was incredibly frustrating for the entire team to have to rework these unplanned changes. Our technical writers were responsible for both API and end user documentation. API documentation deliverables were not yet in scope, but just getting the UI documentation done appeared to be an impossible task.
The turning point…
Oftentimes when we’re at the end of our wits is when the transition suddenly happens. The pain is important in defining the way forward, the way to survival. In learning about Agile we realized we had a tool called the ‘retrospective’ where we could give honest feedback about what was not working. Given we were all so new to Agile development we just didn’t realize how powerful the process to incrementally bring change can be. The retrospective allowed us to course correct and address issues early and continuously improve our product development process. We had Agile evangelists who moved between scrum teams to take notes and give feedback on the process followed by each team. This also allowed them to bring best practices from other teams and share them across the disparate scrum teams. With their help, the decision was made that nobody is allowed propose drastic changes to the agreed design in the middle of the sprint. Any changes will be discussed and prioritized in the next sprint’s design and backlog prioritization meeting. Once the sprint scope is locked, that was it!
Inclusion of technical writers
Over time, the scrum team started seeing the value of including technical writers in the design discussions and sprint planning process. The technical writer gained visibility and could proactively plan their deliverables. They could strategically plant themselves during the lifecycle of product development and suggest improvements early in the cycle. They could influence design change or UI language by playing an end user’s role. As time went on, it became normal to have the technical writer in the scrum team. However, this catapulted into a new problem.
Suddenly, scrum masters began demanding that there should be technical writers to cover their scrum teams. They couldn’t close the sprint as the documentation deliverables were falling behind. This made the scrum team look bad as the definition of done included the documentation deliverables. The ‘potentially shippable’ product would ship without updated documentation.
On the technical writer’s side, the problem was the ratio of technical writers to engineers from the waterfall days would no longer work with the large number of scrum teams! Each technical writer suddenly found themselves swamped with meetings originating from a minimum of 3–4 scrum teams. The maximum was undefined. If they had so many design, sprint planning, sprint demos, and retrospectives to attend, when would they have time to get actual work done? What made it harder was the globally distributed team between India, UK, and multiple time zones in the US! Demand for additional technical writers went to deaf ears. This was partly because most other products had not transitioned to Agile development and the data for ratio of technical writers was not available. There was no data backing the staffing needs and our voices were lost in the big picture. However, I gather technical writer to engineer ratios is still a problem today in most organizations who follow Agile.
Tackling the issue of ‘too few’ technical writers
Technical writers now had to start thinking differently. We needed focus and prioritization to deliver on time. Technical writers would have to figure out how these monolithic guides would be able to handle quick updates with impacts distributed throughout the guide. The guide was never designed with iterative development in mind and redesigning the guide wasn’t a feasible ask.
Dealing with too many scrum teams
We had to communicate that some teams would not be staffed with a dedicated technical writer. Either the technical writer would have to catch up offline on their deliverables or totally drop some deliverables. It was important for a technical writer to work with their product team and management to prioritize some deliverables over others and dedicate people to the high priority deliverables.
However, it still meant technical writers would have to juggle a minimum number of scrum teams. Here are a few tips & tricks from my experiences of being part of up to 7 product scrum teams, yes 7! :)
Treating documentation like a product
Thinking about documentation like a product makes more sense than treating documentation like code. Documentation processes and the collaborative reviews have little in common with coding, but a lot more in common with product development. In fact effective documentation is core to product user experience! Delivering great documentation requires many perspectives from a diverse group of stakeholders including product management, strategy, support, engineers, and sometimes even marketing. If you ever wondered why there are so many people in documentation reviews, it’s because of this aspect.
Building documentation iteratively requires a shift in mindset from planning monolithic guides with multi-page, complex design documents, to simple and focused help targeting the audience’s needs. More traditionally, a product or document was delivered is if it was this giant baby after months of preparation without the product seeing the day for light for the entire time. Once launched, it felt like everyone could catch their breath until the next big release because they were so drained from the build up to the release.
In contrast today, we could begin to align the documentation process closely with iterative product development. Product teams have gone through this mindset shift too. Product owners identify the Minimum Viable Product (MVP) and use it to drive the feature priority for the sprint. The product owner defines the MVP and breaks down the features into their backlogs. They then define the scope of each sprint during the Sprint Planning meeting. When product managers create the user stories, acceptance criteria, and begin working with engineers to code the feature, technical writers can simultaneously start designing help based on the same information. Technical writers now have the unique opportunity to proactively review the product design deliverables, provide early input, and work with the user stories and acceptance criteria to drive documentation prioritization and scope. They can then work collaboratively with the product team to prioritize the key information the audience needs. The process will still be more elaborate for releasing a completely new product, but the MVP clearly defines the scope and priorities of the first release of the documentation. From that point on, technical writers can continue to iteratively include features and improvements in the document.
Listen to customers, update documentation
Listening to customers and understanding how they’re using your product can really help you focus what you write and deliver documentation that actually answers their questions. You are the documentation ‘product owner’ and can choose the next updates based on real-time customer feedback.
Plan the next update based on the backlog priority and actual customer questions after the product or feature is live. The difference is you don’t treat a launch as the end, but rather as a beginning to continuously update and improve your documents. This approach leaves space for including answers to real customer questions that come after a release.
In the long term, the iterative approach can lead to complete, useful, and high-quality documentation focused on the audience’s needs. Listening closely to the customer’s questions and problems faced can enable technical writers to make better decisions, address a few improvements at a time, and as a bonus, engage customers, and make them feel included!
