Technical Writing in an Agile Environment

While working at Savi Technologies, Singapore, the company strictly followed the Agile Scrum methodology. I was with the Typhoon team. Daily the team gathered in one of the cubicles to discuss what we did the previous day, plans for the day, and any blocking issues. During the initial days, I came across the below slangs that were foreign to me. 

• Scrum Team: A scrum team typically consists of five to nine people that include a Scrum Master, s/w engineers, testing engineers, and a technical writer.
• Stories: I used to wonder why they call the feature request as stories. Is it some new adventure stories of Hardy boys or Enid Blyton’s? But I liked the term ‘stories’, It describes why you want that feature to be included in the application.
• Product Backlog: The “product backlog” is the list of stories in order of priority. The stories at the bottom of the backlog tend to be just ideas and perhaps still rather big chunks. They must be broken down into smaller stories as they approach the top of the list. Some people use the concept of an “epic” to group related stories and keep them together as they approach the top of the list. The requirements are collected in a prioritized product backlog by a product owner.
• Sprint Backlog: The “sprint backlog” is the list of stories to be tackled in a particular sprint. During the sprint planning meeting, the project team determines which backlog items go into the sprint. No one is allowed to change the sprint backlog, which means that the requirements are frozen for that sprint. The sprint must end on time. If requirements are not completed for any reason, they are left out of the release and returned to the product backlog.
• Sprint: The iterations and incremental cycles in Agile are called sprints. This is an analogy to what happens in a race. We essentially "sprint" towards a race for completion of the development of software, testing, and documentation. The “sprint” is a period often three weeks during which the development happens. During the sprint, the Scrum team works in close cooperation and meets every day to discuss and resolve any problem.
• Sprint Planning Meeting: There’s a planning meeting at the beginning of the sprint and a retrospective meeting towards the end. The idea is that each sprint delivers a potentially shippable product. In the retrospective meeting, each members' performance is evaluated. Members are free to criticize one another. During my tenure, the ID team received both appreciation and criticisms. But at all times, we took the criticisms in a positive manner and ensured that mistakes were not repeated.
• Scrum defines 3 roles: The product owner creates and prioritizes the backlog, defines the stories, and decides what goes into the next sprint. The scrum master works with the team, fixing anything that’s stopping the team from working. The team does the development.
• Story Points: When estimating the stories, they use “story points” depending on the number of man-hours and resources to finish the task. The story points are expressed as a number, based on the relative complexity of the work required. All the members are given a points card and each member decides on points that need to be allocated for completing a task. And based on the majority of votes, the points are allocated. And they need to justify, why they think, the user story deserves that many points.
• Burndown Chart: This is a graph that lets the team know how much work is left and completed in the sprint. We used Rally to generate the chart. Using this tool, any member of the team or a person outside the team can see at a glance whether the team will complete the work for the sprint.

The good part about Agile development is that writers are involved in product planning, and the documentation development timeline is factored into the product release. Being part of an Agile team has the advantage of making you and your work far more visible. We all met in a meeting room for the sprint planning to commit to the deliverables. We used a tool by the name Rally to define our goals, achievements, pending tasks, etc.

In an Agile environment, developers, QAs, and writers work together to meet deadlines. In addition to the documentation, I also tested features and logged defects. This helped me in gaining good product knowledge. 

Two key points in ensuring a successful scrum are 

• having a set of agreed deliverables and 
• breaking the assignments into small tasks that can be estimated and tracked 

In Agile, any problem that members face is the team’s problem. The role of the Scrum Master is to get rid of any impediments interfering with your work. For example, if you cannot start your documentation because developers haven’t finished coding, then that becomes an obstacle. You can request them for a sample prototype. You do not have to wait until the completion of the coding to start the documentation since that can cause your work to spill over to the next sprint. 

I believe that every company that hires a technical writer should have a well-defined process. It's paramount for documentation development to be integrated with software development.

If you have any questions, email me at abeeshthomas@yahoo.com

7 Deadly Sins of Technical Writing

In my experience as a writer, I've produced documentation that I'm proud of, but I've also written some that didn't meet my own standards. 

 Here are seven problems to look out for to avoid these pitfalls: 

1. Poor Organization: Make sure that your users can easily find the information. It is tempting to organize the content as per what you see in the software application. But ideally, you must ask what the user wants and based on that you must organize your content. 
2. Inaccurate information: Sometimes you may receive wrong information from Engineers and document this piece of information. To fix this issue, you must get your content reviewed by key stakeholders like product owners, scrum masters, engineers, and QA guys to check the veracity of the content. 
3. Outdated information: This occurs when the product undergoes enhancement but the changes are not communicated to the writers by the development team.
4. Incomplete information: Users often need more information than you give them. You must not only document how to perform any task, but also provide conceptual information answering what, when, and why. Your goal should be to tell the users everything they need to know without overwhelming them.
5. Bad sentence structure: The general rule of thumb for technical documents is to keep your sentences short. Whenever possible, use tables, bullet points and numbered lists to organize information.
6. Poor word choices: There are many words that mean approximately the same thing. Depending on the situation, you must make the judgment. When choosing between one or more words ask the following questions:
   
   Which word is the most clear?
   Which word is the most unambiguous?
   Which word is the most accurate?
   
   Once you have made a choice, the next step is to be consistent. Use the same word every time the situation and instructions are the same. For example, if you wrote, Click the OK button or Click OK, the first time, use the same statement every time you expect the same action. 
7. Incomplete Review: Never take your writing for granted if your document has not undergone peer and technical review. You will be surprised to come across errors after review. So it’s worth the effort to get your documents first reviewed by a fellow technical writer and then by Engineers/QA/PLMs. During peer review, you can catch some good errors like missing links or broken cross-references which are normally missed out in the technical review.