January 6, 2010

Agile Tenet #8 – Sustainable Pace

Filed under: Uncategorized — heratech @ 11:09 pm
Tags: , , ,

Magic 8 Ball Eighth in a series of posts examining the Twelve Principles of Agile Software and how each of these tenets can (or can’t) be applied or adapted to technical writing.


Agile processes promote sustainable development. The sponsors, developers, and users should be able to maintain a constant pace indefinitely. [emphasis mine]

Ah, a constant pace. Technical writers aren’t used to that. At least not in a Waterfall development environment. Waterfall technical writers are used to a significant amount of slack time at the beginning of the production cycle, then a stretch of regular work while coding continues, followed by a frantic scramble, often involving overtime, at the end of the production cycle.

One of the big disadvantages I can see to adopting Agile Sprints is that TWs lose the slack time at the beginning of the development cycle. I don’t know a single writer that has enough time to accomplish everything that they’re expected to do. Writers often use that beginning-of-the-cycle down time to catch up on projects that are important but not urgent, like researching writing tools, evaluating documentation processes, designing templates or style sheets, developing style guides, or just plain catching up on everything they didn’t finish in the rush to release. And heaven forbid you need to convert a large legacy documentation set to either a new tool or a new process. How on earth do Agile writers find time for big projects like adopting DITA? The short Sprint timeline makes taking time away from writing for things like conferences, training, and a well-earned vacation a little harder to plan.

Or maybe I’m still making the mental adjustment from being a member of a documentation team to being a sole writer. Even though it’s been a few years, it still feels weird to realize that I am the entire team now. And that if something needs to be done, there isn’t anyone but me make sure that happens.

One of the clear benefits I can see to adopting Agile Sprints is they eliminate that last-minute documentation rush at the end of the release cycle. Or if the scramble isn’t completely eliminated, at least the stress is spread around a bit more evenly so it doesn’t feel so bad. I can really embrace the idea of working at a steady pace.

But I keep bumping up against my fears about who gets to define what a “steady pace” is and whether or not my own personal, idiosyncratic writing style can be made to fit into the Agile mode. What about when I have writer’s block? (Yes, even technical writers get writer’s block.) There are days when the words just don’t flow. This is one of the reasons why I usually have a couple of side projects going at any time. If I can’t get my writing mojo to work, I can switch over and do some training, work on my glossary of product terminology, do some indexing, or spend time trawling the network/wiki for other useful documents that no one thought to forward to the writer. But those side projects, while productive, are not usually the sort of things that would fit neatly into a user story. Thus my anxiety about keeping up a steady pace of work.

Thinking and writing about this tenet reveals my anxiety that Agile is about forcing me to become more productive, ever increasingly more productive. I’m not a slacker by any means. At least not when I compared my production to the other writers when I worked in a doc group. And when I compare my page count from one year’s work to my estimates for what I should have been able to produce (based on the Dependency Calculator), I’m cruising right along. So why do I always feel like business is never happy with a productive employee and always wants more work (and for less pay)? And that no matter how hard I work, it will never be good enough?

Or maybe I’m just feeling uncomfortable about admitting to non-technical writers that the majority of my time is not spent writing, but on other activities? There is this misconception that all writers do is write. Judging from the number of writers blogs I read (both literary and technical writers) most writers spend less than half their time actually writing. Most non-writers don’t understand that all that non-writing contributes to the writing. And that “doing research” is not code for “farting around on the internet.” At least, not usually.

Or maybe I’m dealing with my own attempts at sustaining a constant pace of posting to this blog. And I’m finding that despite my huge list of ideas for possible posts, some weeks it is easier to generate three posts and other weeks it is a bit of a struggle. Of course, the only person requiring me to post three times a week is me. And perhaps the whole point of this post was to get me to realize that the person who has the highest expectations for my work is not my employer, but me. And that I need to give myself permission to find my own sustainable pace.


December 2, 2009

Preparing for Agile – Modular Writing

Filed under: Uncategorized — heratech @ 8:56 am
Tags: , , , ,

Legos If an Agile Sprint is designed to complete releasable code within a 2 – 4 week time frame that means that as a technical writer I should be aiming to have releasable documentation within the same time frame.  The question is how to accomplish that goal?

Whether I would be releasing manuals or online help, it seemed to me that the answer lay in producing modular writing.  My technical writing instructor had taught us to write short topics, preferably of a page in length or less.  This was presented as a usability feature, so that when viewing online help users wouldn’t have to scroll, and when viewing printed manuals, they wouldn’t have to flip the page to complete a task.  I’ve since learned that this style of writing stand alone chunks is referred to as “modular writing.”  I like to think of it as having lots of little Lego®  blocks that I can assemble into whatever form of documentation is required.

Ever since I worked for a company that had been investigating converting their documentation to DITA I’ve been chunking my content into Concept, Task, and Reference topics.  Even if that distinction is made only inside my own head.

I consider Concept topics to be my product overviews, application overviews, business or industry specific concepts, product specific concepts, and other overview material.

When I write procedures, they are always task oriented, and thus Task topics.

I write Reference topics when I’m documenting the UI, (for example listing all the icons in a toolbar) or writing lists of reference material, for example, statuses, commands, or configuration settings.

Now comes the fun part.  *I* write modular content.  But the legacy documentation I had inherited when I started this job was not quite as modular as I would like.  The company had originally had a very competent technical writer, but after she left the company there had been a variety of people contributing to the documentation effort, and as a result the doc set needs quite a bit of Tender Loving Care.  There were two or three separate procedures lumped under a single heading (“Creating and Deleting Widgets”). There were tasks that were buried in paragraphs of text instead of being presented as numbered steps.  There was concept information nestled within the steps of procedures.  And there were topics that stretched on for pages.  How was I going to address these problems in an Agile environment?

I found my solution when I was exposed to the concept of code refactoring in our SCRUM meetings.  According to Wikipeida, “Code refactoring is the process of changing a computer program’s internal structure without modifying its external functional behavior or existing functionality, in order to improve internal quality attributes of the software.”

I’ve adapted the idea of Code Refactoring to my process of ongoing document revision and improvement.  If the developers refactor only when they are touching a particular part of the code, I have decided that I will refactor only when I’m touching a particular part of the doc.  Our documentation is manuals, so when I open a particular chapter to fix a documentation bug or add new content I work on cleaning up the rest of the chapter while I’m in there.  So, for example, when they add a new report to the product, I might do the following to the Reports chapter of the User Guide:

  • Tear apart and revise any topics that need to be re-chunked into Concept/Task/Reference
  • Ensure that each task has a separate heading
  • Rewrite any headings that are not descriptive or task based (the dreaded “Overview” topic and “Settings” topics are ripe for revised headings)
  • Reorganize the topics into a more logical flow
  • Remove any topics that are no longer relevant (reports that are no longer shipped)
  • Add new topics as required (new reports, missing content)
  • Update screen shots if necessary

The hardest part of this process has been wrestling with my own expectations for document quality.  It is painful for me to ship documentation that doesn’t live up to my own high standards.  I want to fix everything NOW.  But I don’t have the time to do that, especially now that I’m only working two days a week.

I’ve had to trust that eventually I will have the opportunity to refactor every part of our documentation set.  As long as there is continual gradual improvement (kaizen) I can feel like I’m doing my job.


Modular Writing Resources
Single Sourcing: Building Modular Documentation By Kurt Ament

Blog at WordPress.com.