Several years ago I was lucky enough to take over the management of the technical authoring for our product. Technical authoring goes by a number of names, "Technical Documentation", "Information Management", "Technical Communication" - all referring to the process of professional technical authors creating user guides. Managing this area was a privilege for me as it has allowed me to learn from some fantastic individuals who are highly professional and work autonomously with little input from me. At the same time, the taking on this responsibility did present something of a challenge. It's a challenge which I know has affected other technical authors working across Agile teams - that of how to synchronise the production of technical documentation with an Agile user story based development process.
An awkward fit
At the point that I was given the remit of managing the technical authoring for RainStor, we had a sole technical author. The documentation that she was producing was a fantastic asset to the company and the quality and professionalism really helped to provide confidence in our product for new customers. At the same time, she was having some difficulty in managing her work around the Agile sprint approach that the rest of the development team were using. The technical author that worked on our product was highly competent and our documentation was a huge asset to our product, but the process of documentation sat somewhat uncomfortably alongside the sprints.
The documentation approach had always been to plan activity on the requirements on a release basis. As historically the team had relied heavily on requirements specification documents this had supported the technical author's approach here given that she could create documentation based on the specification rather than the working product. As the team moved away from requirements specifications to developing based on user stories, with little in the way of up front documentation, she had been forced into capturing the information on new features only after the functionality had been completed. This was done typically once the sprints in which the features had been developed and tested were completed, placing a lot of pressure on her at release time. Also, as many of the design decisions and context around the use of the features were being discussed in the collaboration during the sprints, she was often lacking relevant information and context as she worked on the documentation later.
Looking at her situation, I felt that the solution was clear, however it was going to be a challenge. It was my belief that it was possible to produce the technical documentation for our product within the sprints, as part of the while team process of completing the user stories. If we could bring the technical authoring in as an integral part of the sprint activities then it would not only allow us to maintain documentation that reflected the software being developed. It would also mean that the technical author would receive greater support from the team in completing her activities as they would relate to the development that the rest of the team was in the process of collaborating on at the time. Whilst it seemed apparent that incorporating the technical documentation activities more more tightly into the user story activities was the key to success here, the process of achieving that was not trivial.
The missing amigo
It was clear that the critical point on which the success of integrating the technical documentation into the sprints would primarily depend was the elaboration process. The elaboration of the user story is a critical stage of the lifecycle of a story, where our team aims to turn the 'placeholder for a conversation' into a more tangible set of agreed acceptance criteria and other key elements to support a common understanding. A commonly used phrase in Agile media for the expected attendance list for this elaboration activity is "The 3 Amigos" (George Dinwiddie is generally credited as introducing the term). These three were originally the Product Owner, the Developer and the Tester, and the concept arose to stress the importance of having representatives of each of these disciplines present when agreeing the criteria for success of the stories.
What became apparent to us was that there was a 'missing amigo' in this list - the technical author. In important discussions around the beneficiaries and the value of the developments, it was clear that the presence of the technical author was essential if they were to understand the requirements behind the user stories and document in that context, rather than just from the eventual software behaviour. We made sure that with each elaboration the technical author was invited to attend. This was not always easy as the team were in the habit of very fluidly arranging the sessions and it was easy to forget to invite her along. A few times experiencing the 'post-it of shame' from the author in the retrospective pointing out these omissions was enough to cement the principle into the teams psyche, and the inclusion of the technical author in the elaboration meetings soon became a fundamental principle in our process.
What became clear very quickly was that attending the elaboration wasn't just one way traffic for the benefit of the author. Just as each of the original '3 amigos' roles has relevant input into the acceptance criteria around the story, the technical author too can provide a unique and valuable perspective into this process. Writing the user guides gives a great understanding of how the software is presented to the customer. Technical authors are particularly strong at identifying issues of consistency across the product, and picking up illogical naming and 'developer speak' in naming concepts.
As well as the elaboration meetings we also made sure that the documentation activities were included in other core areas of our development process, fir example we included a column for tracking documentation activity on our scrum board, and any familiarisation demos in which the developer demonstrates changes to the testers, would also include the technical author.
May the Fourth be With You
In recent years we've introduced another technical author to the team. This was an interesting time in testing out whether the integration of the technical documentation in the team would work for someone without the many years of product experience that our existing author possessed. I'm pleased that the new author adapted fantastically well to the approach. He has relished the level of interaction that he has with the development teams and has used that to very quickly build knowledge of the product.
We have not gone as far as integrating an individual author into each of our scrum teams, mainly because the level of documentation between teams varies so greatly depending on the features they are working on. Instead the authors manage their time across the teams, attending standups and elaborations across the scrum teams, getting documentation changes reviewed and approved by the rest of the team as they go along.
In talking to other technical authors across the multinational organisation that I now work in, I've found that doing technical documentation in Agile is a common area of difficulty. Moving from a more isolated role documenting based on up specification documentation to a role with more interaction with the development teams and incremental delivery is not easy. What those responsible for managing the documentation activities has to appreciate is that the reduction in 'in-process' documentation and specification that Agile approaches strive for has a profound impact on the approach to technical documentation. Any initiatives to move to agile in development/testing must also consider a closer integration of technical authoring to allow them to benefit from the collaboration that helps the team to define and refine their specifications. It makes me very proud that our team is integrating in just such a way, and as a result producing high quality documentation during the sprints based on the features delivered within them.
Image: https://www.flickr.com/photos/a440/2065938547/ of the "Four Amigos by Garrett McFann
Post a Comment