Re: When to write in less-than-perfect Agile (McLauchlan, Kevin)

Subject: Re: When to write in less-than-perfect Agile (McLauchlan, Kevin)
From: Janice Manwiller <jmanwiller05 -at- yahoo -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 2 Apr 2014 06:01:21 -0700 (PDT)

To me at least, Agile or not, documentation is as iterative a process as development, and is really a development function. So to wait until things are completely finished seems odd, and reinforces the unfortunate image of technical writers as the people who "type things up" after the work is done.

We do a form of Agile here, although it is less scrum-oriented and more release-oriented. I sit with the development team (the doc team is physically scattered among the dev teams), and attend the daily scrums. Scrums are the dev team only - not product management.

For new features and functions, I tend to start work as soon as the design starts. I attend design reviews, go over UX's wireframes, and review all of the screen text.

During the design process, I start laying out an outline of the content. As development continues, I create and update draft content (in a text or Word doc). I usually maintain a wiki page with the new features for the release and attach draft content to that, to help out QA and others who are interested.

When the feature is checked in, I then dump the draft content into DITA topics and check them in so they are added to the nightly documentation build. I can then get things reviewed by dev almost immediately after they complete the update. Doc reviews are added to the dev Agile boards.

I may have to make tweaks later, after the larger review of the feature by PM, but that's just a fact of life in this profession.


>>In the interest of breaking the latest protracted list-silence...

>>I dunno about you, but the only time I write explicitly about a new feature, AS a feature, is in the Customer Release Notes.

>>In the main docs or Help, I write about new/changed commands and command options, describe and provide procedures for tasks made possible by a new feature, and how to enable new capabilities, and so on. If I have to indicate, at all, the fact that something is new, it's only to lay out how it must be configured/used to either co-exist with existing features, or replace them. "You must stop doing that before you can start doing this..." or "If your existing framistani used frabbleglop authentication and your application requires continuity, then your adoption of the frimmel-himmel is constrained to a subset of ...."

>>In our less-than-ideally-Agile Agile environment, I'm invited to the early sprint scrums, and I find it interesting (and sometimes entertaining) to follow the development of new features, fixes, etc. But I find it counter-productive to start writing and to "produce" for the sake of producing (i.e., demonstrating my Agile spirit) at that early stage.  Whenever I've held my nose and forced myself to kick out some vapor, invariably I've had to trash it or do major re-work during a later sprint (close to end of dev, start of verification), when the new shape of the product is firm.

>>Yes, I know a few people will chime in, right about now, with the rules from Agile god-hood, and how their dev-group's new features are always perfectly self-contained and beatifically modular, and not only can be, but are tested to doneness in perfect tandem with the dev sprints, such that a finishing test/verification sprint is an unnecessary redundancy, just as a production-integration phase is entirely unheard-of in their world.

>>But I suspect more organizations are like us than like the ascended ones.
We exist on a lower plain of Agile wannabe-ness, where testing occurs in stages of greater and greater scope, until the new feature fits into the overall product and doesn't break anything (and also doesn't break or irritate any of the new features being developed by other groups, who might be developing only for a later release), and has been stressed for lengthy periods without failure.  Oh, and we deal with people leaving and with people being glommed for other projects, leaving resource and knowledge shortages. And we deal with upcoming release-scope changes as a new partner or big Beta customer is brought on board with differing/additional needs or a different take on the feature(s) that must be shoe-horned into the release.

>>So do you normally find it valuable to do any writing - as opposed to planning and research - in the early sprints leading to a release?  Or does it reliably make more sense for you to hold off until the Jell-o begins to set a bit, before trying to nail it to the wall?

>>For bonus points, is anyone being successfully Agile, where the Product Manager does NOT attend a significant number of scrums (any...)?
>>For further bonus points, is anyone being successfully Agile where your Scrum Masters are just the engineering team leaders and managers, and NOT people whose primary duty is leading/driving sprints and scrums?  In other words, is a purpose-built Scrum Master necessary for Agile success, or can it be just anybody with the discipline and clout to keep meetings on track and moving briskly, and maybe they read (part of) a book about Agile?
Doc-To-Help 2014 v1 now available. SharePoint 2013 support, NetHelp enhancements, and more. Read all about it.

Learn more:


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @

Previous by Author: Re: Friday Hilarity
Next by Author: RE: Fun: 15 High-Paying Jobs for People Who Don't Like Stress
Previous by Thread: RE: Post-CS4 InDesign TOC fixed?
Next by Thread: Anyone using Wolfram alpha, etc. for work?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads