Guest Blog: Are Doc Sprints Really Agile?

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:

“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.

GUEST BLOG: 3 Ways to Make Documentation as Agile as Development

Welcome back to a colleague and friend of mine, Janice Hamrick, who is an outstanding Technical Information Engineer (aka Tech Writer) and a totally entertaining mystery writer. I read the following three ways to achieve true agility across all development team disciplines and LOVED it.   However, I felt that a fourth point was necessary:

#4 - Be Prepared to Design!

I have often thought that one of the most powerful, yet underutilized, roles of Technical Information Engineers is to make software usable. Sitting alongside of the developers while the software is being created is a huge benefit as they can answer questions like “how am I possibly going to document that???” Serving as de facto Subject Matter Experts across the product, they can also help find potential flaws and opportunities for excellent feature design and simplification. 
~ @MulticastMatt

We all know that the rules of Agile software development decree that user stories must be shippable at the end of a sprint. In other words, a feature must be fully coded, fully tested, fully documented, and fully accepted by the product owner before you can call it done.

To those new to Agile, this seemingly defies the natural order of the universe. After all, everyone knows that documentation always follows development, right? In fact, some teams so firmly believe it’s impossible to have both in the same sprint that they plan to have documentation lag one sprint behind. What they might not realize is that they are no longer practicing Agile development. Because in Agile, you’re not done until you’re done. And let’s face it:

If it’s not documented, it’s not done.

So how do you make documentation as Agile as development?

1. Make Documentation Visible

When story planning, give documentation the same weight you give any other critical-path task. EVERY story should include four documentation tasks:

• Provide content for docs.
• Document the feature.
• Review the documentation.
• Update the doc based on review feedback.

Notice that two of these tasks are the responsibility of someone other than the writer. The team commits to providing information in a timely manner and the team commits to providing thorough reviews to ensure accuracy and completeness of the documentation.

Tip 1: Don’t be afraid to mark the doc task as blocked if time is running short. You want it to be obvious that the story cannot close without its documentation.
Tip 2: Don’t skimp on the estimated hours for these tasks. If you need two different reviewers, put in twice the hours on that task or, even better, put in two review tasks.

2. Be Willing To Write Reality

Be willing to write your documentation to reflect reality. You need to document each feature as defined by the user story, even though you know that eventually you’ll have to rewrite the same topic – either to add the next new bit of functionality or to alter what was previously done because something changed. We’re all familiar with those epic stories that span multiple sprints. The developers break a standard CRUD story (CReate, UPdate, Delete) into three parts and deliver one piece per sprint. Yes, it might be easier to wait until all three are done or even to write anticipatory information, but it’s critical to be able to demonstrate the current functionality when the sprint ends. This puts you in a marvelous position of being able to ship a beta with no notice whatsoever (and yes, that’s happened to me). It also means no revisiting your topics if time runs out and the forecast development changes don’t actually make it into the release.

3. Be Willing To Write Fiction

As a semi-contradictory corollary to the reality rule, be willing to write fiction. Once a feature has been defined for a sprint, you can get started on the documentation. Creating process flow graphics, defining the scenario, providing the key background information, even updating the list of new features in the release notes can all be done before the first line of code is written. Yes, you run the risk that you’ll need to rewrite if something changes, but getting a jump start can be critical to success. You also run the risk of providing unexpected value for your team – timely user-focused questions can help the developers improve the feature as they go.

Tip: Don’t let your fiction be confused with fact. If a feature looks like it’s not going to be completed in a sprint, mark the corresponding docs with a “Do Not Publish” condition and only remove the tag after the code is accepted.

The Bottom Line
So, is it possible for documentation to be as Agile as development? As with all things Agile, success is up to the team. In Agile, everyone on the team is responsible for every story, which means everyone on the team is responsible for documentation.

As soon as your team commits to this principle, the answer is a resounding YES!

How do you keep your documentation agile? Share your tips in the comments. 

About the Guest Blogger

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-winning Jocelyn Shore mystery series (DEATH ON TOUR and DEATH MAKES THE CUT, Minotaur Books).  She has completed the third novel in the series which will be published in 2013 and is currently working on a new and much darker mystery series.  Learn more at www.janicehamrick.com. 

GUEST BLOG: How Agile is Like a Guitar and Tech Info Fits Into Agile Software Development

A colleague and friend of mine, Janice Hamrick is an outstanding Technical Information Engineer (aka Tech Writer) and a totally entertaining mystery writer.  She attended last year's Keep Agile Austin Conference and wrote up a great piece on it.  I'm honored to have her as my first guest blog!  @MulticastMatt

When I told a friend I was attending an Agile Austin conference, she asked me if it was a new exercise program. Naturally, I said it was. Who am I to argue with someone who is willing to believe that I’m exercising? But for those of you who know better, the Agile Austin 2012 Conference was a day-long symposium centered on Agile software development.

Three years ago, I joined Hyperformix as the technical writer for two development teams. A week later, Matt Roberts (soon to be president of Agile Austin) joined as manager and led the teams through a transition from an unsatisfactory blend of waterfall and pseudo-Agile to an extraordinarily successful Agile development organization. Hyperformix was acquired by CA Technologies a year later, and CA is going through its own transition to Agile. As I watch the beginning of this much larger scale Agile transformation, I’m also watching Technical Information trying to find its rightful place in the mix. Technical writers often find themselves left out of the Agile process (particularly when they are not fully integrated into their development teams).

At Agile Austin 2012, the keynote speech by David Hussman set the tone for the day. He said, “Agile is as interesting to agility as a guitar is to music. Both are tools.” He then added, “If you strum a saxophone, it’s not the saxophone’s fault.”

Knowing how to play the Agile instrument is a matter of experimentation, education, and adaptation. It can be a bumpy process, but the most important thing is remembering that the people on your team – including the writers – are like members of a band. Everyone needs to be invited to the rehearsals, and everyone needs to play the same song and keep the same beat.  Holding planning meetings and estimating stories and tasks without including writers is like holding a secret band practice without the guitarist.

As with most conferences, I found the discussions that took place between sessions at Agile Austin 2012 to be as informative and interesting as the sessions themselves. I spoke with one writer who said he didn’t really see the value in retrospectives (the meeting after each sprint in which an Agile team discusses what worked, what didn’t work, and how to improve things).  I was surprised because these meetings not only improve processes but they help build trust among team members. But he then mentioned that his team’s version of a retrospective was an electronic survey sent out at the end of each sprint.  That team is strumming a saxophone, and then wondering why it doesn’t sound like a guitar.  I’ve also spoken with writers who can’t participate in standups because they can’t hear properly over the phone or who are assigned documentation tasks that they can’t possibly complete long after the sprint planning (to which they weren’t invited) had taken place. It’s no wonder that many writers feel frustrated by what they believe is “Agile” when in fact it’s not really Agile at all.

One of the many benefits of living in a town with an organization like Agile Austin is having such a terrific resource to assist you when Agile isn’t working for your or when you think that there must be a better way. Chances are, someone else out there has been in your position and has a suggestion or two that could help make your team and your life easier, better, and more agile.  If Agile isn’t working for you as a writer, then it’s not working for your development teams either (whether they know it or not). It might be time for some guitar lessons.

 About the Guest Blogger

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-winning Jocelyn Shore mystery series (DEATH ON TOUR and DEATH MAKES THE CUT, Minotaur Books).  She has completed the third novel in the series which will be published in 2013 and is currently working on a new and much darker mystery series.  Learn more at www.janicehamrick.com.