December 14, 2009

Adopting or Adapting Agile

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

I’ve decided to change the tagline for my blog to “Adapting Agile to the ancient art of Technical Writing.” It’s a small change, only one word, from “applying” to “adapting.”

Since I started this blog a couple of weeks ago, I’ve been doing some heavy-duty thinking about everything that I’ve read and learned about Agile in the past year. Agile is a process that was designed to address the pain points of developers, not the pain points of technical writers. And I keep coming back to the same thing, TWs are not developers. And I’m not convinced that writing code and writing documentation have all that much in common.

Agile has the stated claim of reducing documentation. But technical writers have a vested interest in documentation, as that is one of our primary functions in the organization. Of course, when Agile practitioners say “documentation” they are referring to requirements, design documents, functional specs, and other product documentation. When technical writers say “documentation” they’re referring to installation guides, user manuals, online Help and other user documentation. (I supposed I should get used to calling what I write “user assistance” but I’m so used to calling it “documentation” it’s hard to make the mental shift.)

Technical writers don’t have a choice of whether or not to “go Agile.” If our development team adopts Agile practices, then we have to follow along or fall behind. Thus, the more I think about it, this blog is not so much about adopting Agile “as is”, but about figuring out how it can be adapted to better meet the needs of technical writers.



  1. […] Adopting or Adapting Agile (Julie Stickler) […]

    Pingback by Dew Drop – December 15, 2009 | Alvin Ashcraft's Morning Dew — December 15, 2009 @ 10:56 am | Reply

  2. I’d like to address the concern that Agile was invented primarily for developers, yet writing and development don’t have much in common. First, any scrum master worth her salt would argue the assertion — Agile was invented to address pain points for *product* development, not *code* development. This is an important distinction, and I’ve been caught missing it myself. So the first question is, does the captain of the team consider documentation part of the product? I believe Scrum specifically accounts for documentation, so the answer should be a resounding yes.

    But since Agile is about *product* development, maybe you have to stretch the definition of your role a bit. Look at the developers — some of them are surely stretching their roles. In the scrum planning session, aren’t they providing feedback on all the estimates (QA and maybe even Doc, included)? Aren’t they providing feedback on product definition, user profiles, and use cases? Aren’t they contributing directly to the scheduling process?

    I like to think of it this way–Product development is an exercise in information management. Writing code is information management. Product planning, project planning, and even testing are all information management more than anything else. Likewise, technical writing. All the team members address different ranges of the spectrum of information management that results in a product.

    If Agile reduces “documentation”, you can’t let that go against your vested interest. Your interest shouldn’t be the page count you produce, it should be your contribution to a product people can grasp and use. Maybe it involves marshaling the design documents for a sprint or two (you work closely with developers). Maybe it involves tracking the big picture, use cases, and user profiles (you work closely with the product manager), since that informs your document structure. Maybe it involves working closely with test because you need to drive the thing before you can write about it.

    My point is, rather than looking at incompatibilities between writers and the other members of the team, you should look for the opposite. I’m willing to bet you will find a large field of information that you rely on as much as developers do. As an information professional, your examination of that field will shed light and add value.

    When you think of it, how much of a normal tech writing job is spent producing pages, and how much is spent understanding what the pages have to be? In my experience, I’d say about 25% of my time is spent actually producing pages. So in an Agile environment the onus is on me to codify the other 75%, and express it as tasks that contribute to specific stories.

    Comment by cud — December 16, 2009 @ 8:14 am | Reply

    • I haven’t seen much written about TW and Agile, so I’m not convinced that the leading Agile minds are considering technical writers when they talk about Agile practices. And I have been reading Agile blogs and books intended for developers and testers to see what wisdom they have that I can apply to technical writing.

      There *are* some major differences is writing code and writing documentation.

      Chunks of code are written for concrete purposes: update this database field, calculate this value, take this user input and generate this response. You can write test cases to evaluate whether or not the code is doing what it is supposed to do. And once a piece of code can do what it’s supposed to do, you’re done. While you may come back at some point and refactor it, chances are, unless a bug is discovered, you’re finished with that piece of code.

      Documentation is less concrete, more subjective. The requirements are more vague: user can install the software, user can complete the task, user can find the command that they need. And whether or not there are useful tests and metrics that can be applied to software is an ongoing discussion in the field. You can write documentation that is grammatically correct with zero spelling errors that is not useful at all. Page count is not a metric of good writing, in fact, if you localize, a low page count (and lower cost) is the goal. As someone pointed out on one of my mailing lists yesterday, writing documentation is an iterative process. As we more thoroughly understand the software and our users, we go back and make improvements to the doc. It is difficult for writers to say that the documentation is “done.” Often “done” means “good enough for this release.”

      >I’d say about 25% of my time is spent actually producing pages. So in an Agile environment the onus is on me to codify the other 75%, and express it as tasks that contribute to specific stories.

      I’m curious to hear how you do this, as I’m currently percolating a post about whether or not velocity should be applied to technical writing.

      I’m not necessarily disagreeing with you. I’m still reading and learning, and I’m very eager to hear about how other writers are making this work.

      Comment by heratech — December 16, 2009 @ 8:50 am | Reply

    • >Maybe it involves marshaling the design documents for a sprint or two (you work closely with developers).

      We’re doing that on our current teams, but it’s only for this project.

      Personally, I think it’s a great opportunity to learn the product. When you read a paragraph and have to look up each of the acronyms to spell them out, it makes you pay attention. Plus, if the acronyms are in WikiPedia, you can get a quick overview of the context.

      One thing I worry about, though, is the reaction of the engineers. As a tech writer, I’ve learned to take feedback as that, feedback; not a personal insult. But when I suggest language changes for clarity, sometimes I sense just a little bit of hurt from the engineer. Many write very densely; each word or phrase is loaded with information for the cognoscenti. But for the managers, QA engineers, junior software engineers, and tech writers, the text is impenetrable. When I break down their jargon-rich expositions, they’re offended. They’re also, I think, perturbed that I made their nice, concise, targeted sentence into multiple sentences.

      I know that part of the answer is to remember to remind them that their explanations are good for those who, like them, live with the technology, but that the audience is broader. We’re not all gurus like them. I have to bring the text down a notch.

      Do you have any similar problems editing specs?

      Comment by duchess — April 23, 2010 @ 2:09 pm | Reply

      • heratech wrote:

        >Often “done” means “good enough for this release.”

        Yes. I find it odd when an engineer who is completely comfortable with the idea of iterative code doesn’t want iterative documentation. Instead, some engineers want it complete and 100% accurate, even if the code was finished the night before the end of the sprint. Of course, we saw the same demands during waterfall development. It’s just that now it seems contradictory.

        Comment by duchess — April 23, 2010 @ 2:13 pm

    Ok… I stand corrected in the claim that Agile requires documentation. I tend to confuse my own experience with the canon. Where I worked well in Scrum, documentation was indeed a part of the product. (In fact, I’ve been lucky in avoiding positions where documentation is an afterthought. I can’t really recall ever being in that position.)

    Of course there are differences. I’m suggesting there are more similarities than you might expect. Especially with the user-centered thrust of Agile, I think that’s true. Your claim that such-and-such development is completed as soon as the feature is tested is analogous to saying such-and-such writing is completed as soon as the topic is reviewed. Neither statement is true… The feature must work within the overall product. Features are interdependent, and as likely to need updates as the documentation of those features.

    In one sense, text is indeed more subjective than code. But as developers become more responsible for user-centric design, their work becomes more subjective. You can say that docs have an objective component… Either you’re writing fiction, or not. The subjective component has to do with clarity (objectified by a good array of good reviewers), coverage, and organization. Developers are increasingly responsible for similar *subjective* results, product and feature evolution is increasingly iterative, and often features have to be released when they’re merely “good enough”.

    I suspect at some point we’ll have to agree to disagree on this issue. That’s OK — the world is full of contradictions. But I urge you to look for similarities more than differences. I believe there’s a gold mine in that.

    Actually, in Scrum this is a requirement, isn’t it? As the story breaks down into tasks, you have to take on a task and estimate your effort. I’ve done this two different ways… Either the documentation for a feature is a separate story, or documentation of a feature is one of many tasks I perform for that feature. In either case, I schedule time for reviewing the design, installing the software (if that’s an issue), test-driving the feature (building example output to satisfy the use cases), outlining the topic (if it’s big enough), then writing, and finally implementing review comments. This doesn’t account for the big-picture planning… Overall doc plan, for example. It also assumes that reviews are scheduled tasks for other team members.

    Comment by cud — December 16, 2009 @ 11:48 am | Reply

  4. In our definition of ‘Done’, the story is not coplete until all the tasks identified in that story are coded, code reviewed, unit tested, documented, documentation peer reviewed, and tested. This is obvioulsy related to the fact that if the task does not require documention then none is developed. But this fact is that this is done at the planning stage.

    We have a dedicated TW for each of our products and each TW covers many teams. The TWs are not colocated to their teams but are seated in a TW area – this enables the TWs to discuss common themes i.e look and feel, style guide related queries et cetera. The TWs discuss the bigger picture planning issues amongst themselves and review this individually with the Product Owners for approval and prioritisation in the product backlog.

    Basically we have approached this problem by asking the question “By the definition of shipable code, does that include documentation?”, If the answer is yes then plan for it in the Scrum.

    Comment by andrew — December 28, 2009 @ 7:07 am | Reply

RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Create a free website or blog at WordPress.com.

%d bloggers like this: