Welcome once again to my friend and colleague, Janice Hamrick, with her latest perspective on helping whole development teams attain agility through effective technical writing. Unfortunately, technical writers, who are crucial members of the product development team, are often siloed for the sake of "efficiency." I've been serving my teams for years by insisting that stories are not complete until there is adequate documentation, and it has driven dramatic positive changes from the perspective of people, product, process, and tools. If you like this post, please check out her other two posts (How Agile is Like a Guitar and Tech Info Fits Into Agile Software Development and 3 Ways to Make Documentation as Agile as Development).
~@MulticastMatt
Some development teams choose to separate documentation from the rest of the development work. In fact, the Society for Technical Communication (STC) recently held a seminar entitled, “Doc Sprints: The Ultimate in Collaborative Doc Development,” which included the following description:
~@MulticastMatt
Some development teams choose to separate documentation from the rest of the development work. In fact, the Society for Technical Communication (STC) recently held a seminar entitled, “Doc Sprints: The Ultimate in Collaborative Doc Development,” which included the following description:
“Many technical writers find themselves in agile environments, where time is at a premium and it can be difficult to pry the developers and other subject matter experts away from their day-to-day deadlines.”
The problem with this practice is that it violates almost every principle of Agile and causes problems for all members of a team.
What is a “doc sprint” as opposed to a sprint?
A doc sprint is just that – a sprint containing only documentation tasks. Often, the only member of the sprinting team is the writer, with nonexistent or at best nominal support from the rest of the team. Dev and Doc are like milk and cookies - they should always go together. If you are having separate doc sprints that lag behind development sprints, YOUR TEAM IS NOT AGILE. Documentation is as important to software development as coding and QA - no story is done unless it’s fully coded, tested, and documented. Why should it be difficult to pry developers away from their deadlines?
If your team is truly Agile, EVERY team member is responsible for every user story. This means that developers are as responsible for providing content and reviews as they are for coding. If a writer is blocked and a doc task can’t be completed, then the story can’t be closed. This provides the means and the motivation for excellent communication and cooperation among all members of the team, and ensures the documentation gets the attention it needs from all concerned. If a team conducts separate doc sprints, dev and QA have already moved on to something else by the time the writer starts and will have to switch context to provide information. Moreover, dev and QA very likely have not budgeted time into their own sprints to work with the writer – after all, their stories apparently can close without documentation. This leaves the writer in the uncomfortable position of “prying” developers away from their “real work” or resorting to begging (or threats). Plus, the likelihood of missing information altogether (because it’s no longer current) or of being shortchanged during review cycles increases astronomically. The doc quality suffers, team relationships suffer, and ultimately product quality suffers.
Why are writers different from any other team member?
The short answer is that they shouldn’t be! However, in many organizations, tech writers report to a different business unit than development teams, a situation that can leave writers feeling like outsiders because they are treated like outsiders. I know writers who are left off mailing lists, who aren’t included in team-building training, and who are sometimes the last to know about feature changes.
For real Agile success, writers must be real team members. It might not be possible or even desirable to change the management hierarchy of your organization, but it is possible for teams to ensure that writers are first-class team members. The first steps include making sure everyone on the team understands this (management support is essential), eliminating doc sprints, ensuring doc tasks are part of the team user stories, and planning for the time needed to provide content, write, and review the doc.
Is there ever a good reason to have a doc sprint?
Probably not. There might be a reason occasionally to have a doc-only user story (for example, if your team decides the product needs a new user guide), but even in that case the team is responsible for content and reviews. No one team member, whether writer or not, ever works in a vacuum. All stories require commitment by the team, and as such should be incorporated into team sprints.
Your thoughts?
Does your team hold separate doc sprints or are your documentation tasks integrated into the development sprints? How does that work for your team and the quality of your product?
About the Author
Janice Hamrick joined CA Technologies in 2010 as the Senior
Technical Information Engineer for the Capacity Management suite of products
(formerly Hyperformix). Before joining
Hyperformix, she spent years writing documentation for backup and recovery
products for a rival company whose three initials shall remain unnamed. It is a
myth that she has worked as a technical writer in the software industry since dinosaurs
roamed the earth, but she does remember when “agile” was something you had to
be to avoid the saber-toothed tigers.
Outside of work, Janice is the author of the award-winningJocelyn Shore mystery series (DEATH ON TOUR, DEATH MAKES THE CUT, and DEATH RIDES
AGAIN, Minotaur Books), and is currently working on a new novel. She lives in Austin, Texas.
Egads! Yes indeed, Doc sprints are bad ideas. Tech writers should always be part of the team working on customer facing documents as their contribution to working software. I've incorporated Tech writers into all my Agile teams. Sometimes though, we've had a tech writer support 2 or three Scrum teams which can be challenging. My "Robust Agile Organizations" article includes the tech writer as part of the Development Team (see: http://cmforagile.blogspot.com/2011/06/robust-agile-organization-core-roles.html )
ReplyDeleteThere never has been a correspondence between how much code it takes to implement a feature (or story) and how many words it takes to document it. In one extreme example, I once one saw a development team work for months rebuilding the architecture to remove a limitation from the product. The documentation effort required was to remove three statements from the docs that described the limitation and make a note in what's new. It took 20 minutes.
ReplyDeleteI'm not a fan of doc sprints, but I'm also not convinced of the virtue of making docs part of a dev sprint. Agile is a software development methodology that does not necessarily translate whole to other disciplines. There are definitely advantages in terms of team cohesion, but it also makes the sprint more complex, which isn't particularly agile. An alternative is to create a lean docs process that integrates with dev's agile process, but which is designed for docs specifically, rather than forcing docs into a process designed for software development. In particular, I would suggest that such a process use kanban rather than sprints.
Absolutely agree with your statement about the lack of specific correlation between quantity of code and documentation. But I'm guessing you could make the same argument about QA, design, etc. The main culture we're trying to drive is that no story is done until it is ready to ship, including documentation. I always say that the best documentation may be no documentation at all, which is *possible* if the product can work simple enough to not require it (google, expedia, mint, etc.) This helps pull documentation into the earliest stages of ideation/story grooming. Ultimmately, we practice that documentation is a whole team responsibility and there are no hand-offs to "someone else" (queues/waste).
DeleteBy having the whole team responsible within the context of a sprint, certain coders have developed adjacent skills on writing if there is a spike in demand. Our writer (Janice) has developed skills in areas such as testing since she probably understands the end-to-end product experience better than anyone else. Coders will help her automate things to further eliminate waste in the process and have made changes in continuous build, integration, and deployment to always have the latest docs available. We're maximizing the whole and developing so-called "T-Shaped" team members.
In my interpretation and practice, I believe that frameworks such as Scrum serve whole product development teams as opposed to simply coders.
Ultimately, I think we've inspected and adapted to maximize the work/value produced by the team. We have certainly followed some of those lean techniques that you've mentioned as well along the way.
Thanks again for the feedback--I'd be happy to hear any more thoughts you have on the subject!
@MulticastMatt
This comment has been removed by the author.
ReplyDeleteInteresting...Our company, SmartBear Software, is the developer of the premier tool for peer code review. We recently modified the product to allow for document review (and other file formats are coming) primarily for the reasons you provide here -- to involve more poeple in the development process. We found a big need not only for tech writers but for developers sending a design doc for review prior to coding, for product managers sending stories for review, and for QA folks to send around test plans for all to review.
ReplyDeleteThis is all especially helpful in Agile environments, as you said -- but especially for distributed teams. Peer review of code and documentation brings team members together and ensures that everyone is on the same page -- from the stories, to the design, code, documentation, and QA.
@markmhammer
Absolutely agree that documentation sprint is a bad idea. Agile demands more collaboration. Collaboration between development, QA, and documentation teams. Having a separate doc sprint defeats the purpose of working in an Agile environment and may push the doc team into wilderness.
ReplyDeleteIdeally, a Scrum Master, during the sprint planning, must ensure that part of a developer / QA effort should involve providing information to the writer. This ensures that the development team does not have to take time out from their day-to-day deadlines.
Any unfinished documentation that carries over would be (documentation?) debt, accruing interest and cutting into ROI. A way to avoid this situaton would be to include the completion of essential docuemntation in the definition of done.
ReplyDeleteI agree with Matt that (almost all of) the best software needs no user-facing documentation.
I have a question on this front. Most doc teams have a backlog of items that need to be added to the docs that are not part of a story as it relates to what is being worked on for dev. For example we might have some documentation that is missing on a particular subject, but doesn't relate to the sprint. How are you handling these items. Are they added to the sprint as stories that everyone agrees to? If so, how does your different development teams feel about this. How do they guess the points when they might not be involved much with it. Or do you run a separate doc sprint for this work separate from the regular sprint.
ReplyDelete