Case study—Establishing product documentation as practice in agile
Download as DOCX, PDF2 likes890 views
1) Arya, the documentation lead, pushes for documentation tasks to be formally included in an organization's agile project management process through the use of feature sheets, as large documentation projects are currently not properly planned or resourced. 2) After successfully making the case that rewriting a technical guide requires as much effort as a software feature, Arya works with the product manager to create a feature sheet for the documentation work. 3) With project artifacts now reflecting the documentation task, the team is committed to the work and provides support through the regular process, allowing Arya to successfully complete the updated guide.
Case study—Establishing product documentation as practice in agile
- 1. 1 Establishing documentation as a practice in Agile By Sudhir Subudhi, Lead Technical Writer, Process Expert Jun 11, 2014 Arya walked up stairs fast, thinking not to be late in the meeting today. Enters the meeting room at the corner, 5th floor of Techno Building, housing World2Net (name changed), a telecom based software company. “Hello”, said Arya, looking at the colleagues, from all cross functional teams, in the Network Simulators project, seated in the room. Srini, the Development Lead, wanted to have a lighter discussion before the meeting starts. “Guys, look who we have here—the UM (short for User Manual)”. The project team would usually call Arya, the Documentation Lead as UM, to make fun of him and documentation. The trend was started when Arya started raising multiple issues and concerns with the project team on the management and execution of documentation tasks in the project. To the project team, no body reads a user manual, so documentation work is of least priority—Period. Dipali, the Testing Lead, joined Srini, “why did you come, Arya? We have had many such meetings without your presence. We would send you an update, like always.” Everybody chuckles. Arya, knowing that he is at the receiving end, stayed calm, and said, “I know”. Susant, the Project Manager, informed others, “I have called him. Mak checks every cross-functional team’s presence, especially the doc team”. “Oops, this Mak! What this guy is made of? Just chokes us.” Mak, the Product Manager, who recently took charge of the Network Simulators product, is truly a business professional, keen on quality delivery. From the day Mak joined the team, he has raised many serious concerns about the way the product, the process, and the project management. In his observations, the incorrect management of things internally, is hampering the quality of the released product. “Guys, it’s time. Let’s join the bridge. Mak could be waiting”, said Susant. Lily, the System Engineer and Technical Architect, dialed the bridge number and the password. The offshore product team joined the call with Mak, who works from US. In the following moments, everybody introduced each other and had an informal chat. Then Mak started, “So, this meeting is for C1 of VOLTE. You must know that having this feature in this release is of high priority. Many of our customers are waiting to have it. Feature backlog # Feature Priority Release Status . . 15 VOLTE FS: LTE_1101_VOLTE High 3.1 Schedul ed . . Many organizations fail to follow correct agile guidelines. Thus the project management is hit, leading to product quality degrade.
- 2. 2 World2Net followed agile process (customized FDD). The Product Manager would find out and analyze the customer requirements, defines a feature for every customer requirement. System Engineers and Technical Architects create Feature Sheets (FS) for every feature, in consultation with the Product Manager. The Product Manager approves a list of features to be release candidates. The work starts for only these features intended for the release. Every feature gets developed in parallel, and goes through a set of six milestones, from C-3 through C3. Out of these C1 is an important milestone, which confirms the commitment of the project team to develop and deliver the feature. “Lily, could you run us through the FS please?”, Mak said. Lily started scrolling down the FS, explaining the details to the team. “Ok. So, are we committing to this feature in the current release? Any concerns, guys?” Arya, immediately said, “I do.” “The estimate section in the FS says the documentation effort is included in the estimate. But, the documentation team is yet to send an estimate against the feature. And I suggest to add a Documentation Estimate sub-heading to capture the documentation estimate exclusively”, said Arya. From the past email communications, Mak has been already appreciative of Arya’s efforts to raise the quality of documentation. He is also aware of the messed up agile process followed in the team. Mak, asked Susant to take Arya’s concerns as actions points and close the C1 milestone, after the action points are resolved. While closing the meeting Mak mentioned that he is planning to have a major upgrade in the product documentation to raise the quality. He will soon communicate about it. After a week, Arya receives an email from Mak: Feature Sheet Title: LTE_1101_VOLTE Author: Mak, Lily Customer requirements: … System analysis and plan: … Product requirements: … Estimate: … Release Process Legend: U0: Release candidates selected. Start of project. C1: Feature is committed. C2: Feature is developed. C3: Feature is tested. U2: System integration tested. Product release. Project complete. Note: Prior to C1, every feature go through C-3 through C0, which are for domain analysis, approval, solution design, and so on. U0 U2 C1 C2 C3 F1 F2 F3 F4 If the documentation effort is not scoped in the project, the documentation tasks will miss the project team’s attention.
- 3. 3 Minutes later Arya receives another email from Susant. Like always for any documentation issue: “LTE User Guide is a 500 page long document. The effort to redesign and rewrite it from scratch would take a huge effort. It would need the involvement of the whole project team. As per the crunch release schedule, it seems to be an impossible task. And with the uncommunicative, uncooperative, ill visional cross-functional teams, this will never be a smooth ride. God help me!”, thought Arya. Arya didn’t respond to the email for a day. He thought a lot. Remembered how voluntarily in short stints he has been raising the quality of documentation. He remembered how he has stood up against the development and testing guys to close documentation issues. However the scale of this new task is very different. He can’t take the responsibility alone. The team has to take it. But the team is never been interested in documentation. Eventually they will desert the task. At the release time the User Guide will be in a meshed up state. From: Susant To: Arya Subject: RE: Need to redesign LTE User Guide in Release v3.1 FYA. Regards, Susant From: Mak To: Susant CC: Lily, Srini, Dipali, Arya, Deepak Subject: Need to redesign LTE User Guide in Release v3.1 Dear Susant, Please look at the following: Customer feedback (based on recent survey): “We couldn’t find a lot of information from the LTE User Guide. We require it to contain all basic technical information required to conduct a test.” - Engineer at Alcatel Pending documentation defects from customer: QC 12111, QC 12345, QC 12456, … Total 32 defects Product Line Management comments: “Our customers refer LTE User Guide the most. We have had many negative comments from our existing customers. We need to redesign the document from scratch.” We need to address the above raised issues in the coming release. I.e. in Rel v3.1. Please do the needful. Regards, Mak Customers are increasingly demanding quality docs as their operation are hit without it. Effort for big documentation works equal that of a feature. The project must accommodate this effort for successful completion.
- 4. 4 Arya will become the scapegoat. Something needs to be done. But, what, and how? The next day, Arya wrote back: Hours later Mak had a call with Susant and Arya. Susant expressed, “the documentation effort is included in the development efforts of features. We never had a documentation work as a feature. How can we release it as a feature? Customers look at features for added functionality, not documentation upgrade. Who will write the FS here? Frankly, this is not the practice we follow in our agile process.” Arya countered, “An agile project runs to deliver on FS only. The project resources stays focused on FSs that are release candidates. You can never deliver on a large scale work that is not made a release candidate through the project/process artifacts. The project resources will stay involved in other release candidate works and will miss to work on this. Why you want to take this work as a voluntary work? Are we doing this for our personal improvement? Who will own responsibility? How would you budget for some new resource requirements if needed to deliver on this work? This is for the project/product. So map it to the project through its usual artifacts. I am done with voluntary work. I will work if the project needs it. And the project needs to show, that it needs it.” Arya didn’t wasn’t to miss this golden opportunity. Because of his voluntary and proactive interest the documentation management is being stabilized in the company. If this idea succeeds, he can demand a FS for each small or large scale documentation work. This could actually establish documentation work as a practice in the project. In his mind he knew that FS is the key. Without a FS, the team would never commit to the task. Tasks such as information gathering, document outline preparation, technical review, etc. would be hit. The project team knew, one more FS means some more work. The tight work schedule they go through, this new task would make it a little worse. So, they didn’t desire for it. It was evident from their communiqués. Although they were reluctant to try this as a new practice for the documentation, From: Arya To: Mak CC: Lily, Srini, Dipali, Susant, Deepak Subject: RE: Need to redesign LTE User Guide in Release v3.1 Dear Mak, It would be nice to redesign the LTE User Guide from scratch. Here are my observations/concerns: As per my initial estimation it would take us approximately 420 hrs of only Technical Writing effort. This effort nearly equals the effort consumed by an average feature to develop. This work needs to be tracked through the release, with the milestones and other project artifacts. The project needs to commit to this work and needs to adopt this whole effort. So, I propose creating a FS for this work, and making it a release candidate. So that we can track this using the project/process artifacts. Regards, Arya Project artifacts drive and track a project. To establish a work as a practice, one must make sure the artifacts reflect this work.
- 5. 5 seeing Arya is the only person who could drive this task, and Mak wouldn’t relent, they kept mum. Mak seemed upbeat. He needs the new document to please his existing and new customers. He can’t take a chance to fail. This new FS approach for documentation work may enable him to achieve the goal. Mak subsequently issued a guideline to the project team to create an FS on the new LTE User Guide, and cooperate with Arya, as he drives it. Arya gets the FS template from Lily and starts writing it. He has to write it optimally as it would be reviewed by all, and it will be passed through milestones. Soon, Arya calls the team to review the FS and commit to it in the release. This way, the team clears the C1 for the FS. Eventually, Arya drives the work through a regular Document Development Life Cycle process, and everybody in the project, members from all cross functional teams coordinate, cooperate, provide information, write, and review the document content. Through frequent minor hiccups the work comes to a successful finish. The new and refreshed LTE User Guide is ready. All milestones are cleared. Now, as the system testing is in progress, Arya, adds the documentation upgrade work as a “What’s new” item in the release notes. As always, after successfully releasing the product, the team goes to party. After a couple of drinks, the team is in full merry making mood. Arya, while dancing himself, sees the whole project team dancing to the tune of music in coherence. “It is always a team work, it’s always a project work. Documents are not outside product. Documentation team is not outside project team. Documentation effort is not outside project effort.”, thinks Arya. The whole team breaks his thoughts with loud noise, “wohooo…” By Sudhir Subudhi, Lead Technical Writer, Process Expert Email: sudhir.subudhi@outlook.com Linkedin: in.linkedin.com/in/sudhirsubudhi Skype: sudhir.subudhi Twitter: @sudhir43 Release Note LTE v3.1 What’s new: … Enhanced and redesigned LTE User Guide … Defect fixes: … QC 12111 QC 12345 QC 12456 … Feature Sheet Title: LTE User Guide_upgrade Author: Arya Customer requirements: … Organizational requirements: … Analysis and plan: … Product requirements: … Documentation requirements: … Estimate: …