Write with Agility
In the summer of 2012, internal business partners approached our team, the MasterCard Customer Technical Communications group, to request the development and delivery of an enormous amount of documentation within an aggressive timeframe. Unfortunately, requirements documents would be delivered incrementally, so we had to work with the information as we received it. It was going to be a challenge to meet the business owners’ needs!
The traditional writing processes that we had in place would not allow us to meet their deadline. On average, a writer in our department takes a minimum of 6–12 weeks to author a document and get the necessary feedback in multiple cycles of 5–7 days in duration. With complex requirements documents to understand, drafts to prepare, and several review cycles by many subject matter experts (SMEs), any number of delays can occur. If a question arises, it may take several days to determine exactly which SME can answer the question, or it may take a developer several more days to research and respond to the question.
With this new request to provide an undetermined number of documentation deliverables within a seemingly impossible timeframe, it became clear that we needed a new game plan—literally. Using a football analogy, we envisioned “game day” as the day on which a team of multiple writers would collaborate with external resources—business owners, stakeholders, and developers—to write, revise, edit, and review the content to prepare it for legal review. With only a few weeks to produce documentation using an iterative and incremental approach, we were challenged to get out of our comfort zone and “into the end zone.”
We share some details about our experience in the “Coach’s Corner” section later in this article. But first, let’s briefly discuss the methodology from which this workshop originated.
Agile methodologies have become common in many business environments. Though agile development is defined in a number of different ways, our group has come to think of it simply as fast, flexible, and face-to-face. Within agile development, Scrum is the framework used to drive the agile process (www.scrum.org). While Scrum provides a basis for flexible and iterative work, technical documentation requires more structured schedules and review cycles.
Pietro Margutti first discussed the positive aspects of including a single technical writer along with a number of developers on the Scrum team. By increasing the number of writers, we adapted Scrum techniques to create an Agile Writing Workshop where we could produce documentation efficiently and within the required short timeframe.
The workshop consisted of all the personnel required to produce the documentation, working together, in the same room, in a single day. Like a Scrum team, the writing workshop team would require the participation of resources in various roles. The collaboration would occur in a fast development sprint cycle, and both the source content and the output would be delivered incrementally, before starting the next sprint. Could we be successful adopting this method to increase the amount of content we could deliver and decrease the amount of time in which that content could be provided?
To be successful, we set initial expectations, defined roles and responsibilities, provided ongoing communication, and facilitated rapid decision making. We delivered 11 documents in four weeks, allowing for an additional two weeks for legal reviews and final updates. In PDF form, the content that resulted spanned more than 1000 pages. Our stakeholders indicated that they realized substantial savings, and they were impressed that our team could develop content so quickly.
Beyond the metrics of cost savings, we realized some other benefits, as well. By working as a collaborative team, each writer developed experience, skills, and confidence in our authoring tools and gained a better understanding of DITA. Additionally, the workshop tested our information model and department standards, resulting in some adjustments for both. Finally, the process was a great team-building event that created a measurable cultural change, one where we pooled resources and created an “all for one, and one for all” philosophy.
Note: While our team used the topic-based structure of DITA, the following method can be applied to any writing project. It is not dependent on specific tools, skills, size, or scope of the documentation.
Don Cwiklowski served as “coach” for the Agile Writing Workshops. He presented the Agile Writing Workshop experience at the Best Practices Conference 2012, in Monterey, CA. Here he provides a summary of this presentation using a football analogy to illustrate the preparation and teamwork required to “win the game” by providing the content requested within the timeframe required.
To draft the right team for an Agile Writing Workshop, you must first scout the talent. An essential component of this initiative is writers working in collaboration, so keep in mind that it’s not always the best players that comprise a team, but rather the players that work best together.
A season is a specified length of time. For us, the duration of each workshop was limited to individual eight-hour sessions, once a week, for four weeks. Each session required analysis, preparation, development, and post-work metrics. Limiting the number of sessions allowed each resource to understand expectations and to commit a specific amount of time to the project. The few days between each workshop session were sufficient enough to evaluate and to send documents for final review and to analyze the next set of information as it became available.
Training Camp The Agile Writing Workshop had multiple goals. Our original concept was to use real data and develop the workshop as a training exercise to practice DITA topic-based writing, document construction and development, and use of our authoring tools.
So, why not attempt multiple goals? Use the workshop to train. Use it to build a team. Use it to produce documentation.
The Game Plan
Producing documentation using agile methods is dramatically different from what most writers or stakeholders may have experienced. There are several action steps important to designing an effective game plan.
- Sell the idea to the stakeholders. The business owners, analysts, developers, subject matter experts, and reviewers should be prepared to fully participate in the sessions.
- Be open and honest about using a new methodology. Be clear about what is required in resource and time investment. Engage and involve management. Do not work in a vacuum.
- Assemble an effective team of writers. Skill level is not as important as flexibility and the ability to work well in collaboration with others. Pairing inexperienced with experienced writers serves as a good training and development exercise.
- Analyze the information and build topic structure. Thorough analysis makes everyone more efficient. Everyone needs to know his or her position and the playbook.
- Enjoy the game! This method is fun.
For a successful workshop, creating a strong team requires the participation of resources in various roles. Additionally, you should set expectations with each team member. Consider making a list of responsibilities for all team members so their roles are clearly defined.
Beginning with the writers, try to predict the amount of content that you will be handling and plan accordingly. The size of the writing team will be directed by analyzing the scope of source documentation that is provided and the amount number of content deliverables that are likely to result. Using too many writers will be cumbersome, while using too few will diminish the potential for the learning opportunity and the collaborative environment. For our workshop, we used eight writers. Generally, trying to get that many writers to give up about 30 hours to work on another project is impossible and can lack consistent and cohesive results. However, requiring their involvement for only one day each week for four weeks reduced the disruption and allowed them to maintain work on other projects during four workdays each week.
Have a project manager (PM). The PM will organize the personnel, handle challenges, and make sure the operation runs smoothly. The PM will arrange equipment, schedule facilities, and handle the day’s agenda.
An information architect (IA) is a must. The size of the project may require multiple architects to tackle specific construction or outputs. The architect(s) can perform analysis and build the necessary structure if you start with basic requirements or specifications. Our architect prepared the information in spreadsheets prior to the workshop (more on that later). Maps were not pre-built, but topics were pre-named and a basic structure was designed in advance.
If you’re writing in a code or topic-based environment, include a code expert on the team. For authoring in DITA, or another markup language, providing instant code reviews will help to eliminate problems when it comes time to produce the output. Also, your code reviewer is a backup IA, and he or she can answer questions about the information model.
An on-site editor isn’t a luxury, it’s a must. Your editor can establish not only the editing process as topics are delivered, but also can answer questions about brand standards and terminology. If the editor sees recurring issues within the content, he or she can immediately clarify issues with all the writers in the room. Posting naming conventions and similar editorial decisions where everyone can see them while authoring helps writers with consistency as well.
Depending on the department, the type of project, and the types of output, a production analyst or web developer may be necessary. Again, this is a role that may seem like a luxury, but the goal is for the content to be as complete as possible at the end of the day.
Finally, all the business owners and stakeholders aren’t required to be in the room; after all, there may be dozens. But the primary business owners must be present to take ownership of issues that could arise and to escalate to the appropriate persons for immediate resolution.
The main developers and key stakeholders also will need to be available, but not necessarily on site. The speed of the project and clarity of the content production increases with the more reviewers that are available to answer questions about requirements and unfamiliar terminology.
After all the players in the lineup have been recruited and given a list of expectations, it’s essential to promote teamwork. Because the original goal was to develop the workshop as a training/learning exercise, we assembled a team with writers of varied skill levels. Each tandem paired an experienced writer with a novice. The pairings produce great collaboration and challenged each member—which can be a great learning tool for all involved.
All analysis is the responsibility of the IA. The IA should build a spreadsheet that contains everything the writers will need. Use the spreadsheet to track the information architecture, writing assignments, and topic comparison. Include columns for the original table of contents, if the information is derived from source documentation, or include headings from specific requirements or specifications.
We tracked several categories, including topic type, reusability, structure, assigned writer, special notes, and completion. You can include all methods of publishing and production notes. The spreadsheet can contain everything about the project.
Analyze the information to identify more opportunities for reusability and better topic construction. Determine a preliminary architecture, and gauge the amount of information in each topic. Develop a plan to attack the topics for greatest efficiency and maximum success according to your writing teams. An experienced IA can make this process smoother and more detailed.
Leave preparation to the PM. Begin with reserving the meeting space and having plenty of room to make the day comfortable. Confirm that the logistical aspects are in place, such as Wi-Fi and power strips. Ensure the availability of collaboration materials like dry erase boards and large notepads. Prepare for everything so you can eliminate surprises, like “Don’t forgot his power cord.”
Make sure everyone who plays the game knows his or her position. The method is to have a solid foundation in place, assemble the players, produce the documentation, solve problems, and plow through a basic review. For our workshop, we prepared content for delivery for legal review, and the lawyers knew that we were working with agility in mind. Be clear about the expectations for reviewers to ensure that the agility isn’t lost in endless cycles of review. In the end, if the players know their positions, then the goal will be achieved.
Time to execute the strategy and game plans developed and tackle those unplanned surprises. After introducing the resources—business owner, writer, editor, developer—give the pre-game speech where you explain the game plan, lay out the day’s goals and expectations, and explain the plans for each writing tandem. Stress collaboration. Through the course of the day, new ideas and new approaches will arise; embrace this opportunity to learn and share. We found that our usual methods and information model were put under a microscope.
Take advantage of the resources you’ve assembled. The architects and DITA experts will be called upon to address questions on DITA usage and topic-based writing questions. As writers dive into the material, ideas will evolve. Encourage this and capture the ideas, as everything is up for discussion.
Use the external resources, business owners, stakeholders, and developers to get immediate access to answers and to remove stumbling blocks. Engage business owners and subject matter experts as much as possible, remembering that everyone in the room is one team with one goal.
Complete the topics and assemble the maps (for DITA). Maps can be developed ahead of time if the content allows for it; however, using the agility method may result in dramatic changes to the structure of the content. If the analysis has a solid foundation, the basic structure allows for realignment. The architecture will develop through the course of the day, so you must have an adaptive strategy and be flexible.
At the end of the session, have a post-game wrap-up where the team can assess the day’s work. Take time to celebrate your achievements. Whether the workshop project took a single day, several days, or becomes an ongoing exercise, it is vital to amass results.
Because the workshop serves as a learning environment in addition to fulfilling a business goal, look for opportunities to apply what you’ve learned to your whole department or business. Identify successes and failures because even with the success of it all, improvement is possible.
Using an adapted Scrum framework, we were able to achieve our “goal”—to meet our business partners’ needs to produce the documentation required within the short timeframe established. In addition, the effort raised awareness about techniques that we could adapt and employ innovatively to other areas of the business.
About the Author:
Don Cwiklowski is a Sr. Technical Communicator with MasterCard Worldwide. With a B.A. in History and a Certificate in Writing he fell into the world of technical writing by accident taking a job with a major automotive service equipment manufacturer. During the last 14 years he has gone from a novice writer to experienced professional and a driver for documentation change. At MasterCard he isn’t just a writer and web developer, but is exploring XSLT, and all forms of documentation production and delivery. Outside of work, Don is a huge Missouri Tigers fan, Cardinals baseball fan, dart player, and an avid bad golfer.