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.
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.
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.
Thanks, Janice, good stuff! The only tweak I would suggest is instead of documenting the feature (in #1), document the usage (or update the documentation for a particular goal/use when a new or improved feature makes it different).
ReplyDeleteThat may already be exactly what you were thinking, but I've seen too many products approach documentation by scanning the menus and making sure all the items were documented, instead of thinking about the goals of the user and providing the documentation / tutorial about how to accomplish the goal with the product.
As an example, in visio, you want documentation about how to create data-driven shapes from a spreadsheet, which happens to include connecting the spreadsheet as a data source. You don't want documentation about how to connect to a spreadsheet as a data source.
Thanks again,
Scott
Good article. I think one thing that is missing from this article is technology. I believe that there are great ways to be strategic about the code and tests that are written and leverage that into documentation.
ReplyDeleteOff the top of my head, I could imagine writing documentation for a publicly accessible API. Perhaps, if Java is your language, spending time writing a custom doclet to transform the javadoc comments on your source code into a published document may help.
Additionally, there are several BDD frameworks out there that call for tests to be written in plain english. Try leveraging something like Cucumber's gherkin language to not only specify a test, but be the initial launching point of the published documentation. As a side note, BDD tests (or tests in general) can oftentimes do a sufficient job by themselves for offering up internal documentation.
What I'm getting at is to try to move as much of the documentation as closer to the code as possible. What is that going to buy you? Well, it should encourage developers (and everyone really) to work well with your tech writers. It should also increased shared understanding across the team and the organization of the products being built. It helps engage everyone on a team oriented effort of raising quality of code and documentation.
That's an increase in teamwork, increase in communication and understanding, and some more increase in teamwork...because it's important. Those are some things that really help to make an organization Agile. So, why not try to extend it to producing documentation as well?
Granted, this kind of thinking does call for some overhead to get infrastructure in place. It does call for discipline as developers (as well as tech writers) will need to be sure that code comments and tests are well written. But, wow. Think of the benefits. In a continuous deployment shop, you could write and document a new feature and watch as both code and documentation go to production with a high degree of confidence in the quality.