Define “product” please. Do you mean “software”?

If not then the Product Manager is, ultimately, responsible for the entire product and if he/she fails to provide the inputs the Documentation Manager requires (be they whatever format) then he/she is presuming the product needs no documentation.

Ok, this is an overly simplistic view but I can envisage the Product Manager quickly catching on to the fact that if they don’t produce such a document… hey look the Documentation Manager does it for them!

Personally, I don’t have the time and I have plenty of other things my writing team can work on.

I am glad, however, that you are also considering the ‘include the writers’ angle as well because I think this is a significant problem. I have seen how the writers bring that extra voice/perspective into the elaboration – often the user’s voice to the best of their ability – and it enhances the feature tremendously. Plus, often the writers are the best at distilling the decisions made into a follow-on message that is redistributed through the team to add to the story’s development.

I feel that all sides benefit from the writer involvement, and I’m curious if you publish this article whether there is disagreement.

Could be interesting … have fun with it and I’ll be here to watch/contribute!

Virginia

You raise some good points about the benefit of a well defined roadmap.  Documentation managers should insist on this point, and a good ARD (Agile Requirements Doc) should map to it.

Thanks,

Eric

A very thoughtful response.  I agree that writers should be part of the team.  By way of explanation, the thrust of this article is the need for a spec, which some Agilists repudiate as outdated.  The focus of my thoughts was on how such a spec would be written, and so I wasn’t thinking about team composition.  Your point, though, is a good one and could be the subject of a subsequent article.

To illustrate your point, I could cite the experience I had with one client who included the Documentation Manager as the focus of a few user stories.  It was remarkable how the design of the product was improved by adding that consideration.  To make this a repeatable event, writers would have to be part of the team from the beginning in order to contribute those stories to the product backlog.

The more I think about this, the more I like this for an article.  Great suggestion!

Eric

I’m not sure if the presentation will be online (I think that’s up to the STC) but I am planning on putting a modified (and expanded) version on the web. Probably on this website or on the Agile Alliance website (I’ll link to it from here).

It’s hard to condense 60+ slides into 15 for a 45 minute presentation.

Mike

Will the presentations be available online, do you know?

Virginia

An excellent article. I think you make a clear and logical case for an Agile requirements document. I especially like your DIY approach when all else fails.

At my company (a start-up), doc is involved in the process from stage 1, roadmap roll-out. This being said, we often do not get the ‘classic’ Agile requirements document for our quarterly release. However, we have been trained (like a puppy getting its nose swatted) to pick up on much of the requirements in our revision planning sessions.

The culture at my start-up is everything from cocktail napkin specs to good classic Agile design docs. The key to success in either case is for the roadmap to be well defined and the goals/themes of the release be well communicated.

If you can get those, and if the Dev Manager doesn’t have them the project is doomed anyway, you have a shot at delivering doc that satisfies the 80 of the 80/20 rule.

Virginia, it looks like you’ve been reading my notes for my STC presentation in Philly.

Mike

As a technical writer who works on an agile development team, this old pattern is a big mistake.

The writers bring far more to the development effort than simply a noisy voice trying to write the end user-facing documentation. When involved in the story from the beginning, they bring a user face to the elaboration of the feature. In the absence of a user-interface expert, the technical writer is often the next best option for input into the screen design (having often worked with a larger scope of the product than the developers themselves).

Because they are involved in the elaboration, the writers understand the ‘why’ of what this feature is about, which drastically improves the quality of the content and moves it from the amateurish attempts of this does this and that does that (plus a glossary and a shortcut key map). Plus, there are fewer questions to ask the developers because the opportunity to understand the feature’s functionality occurred through elaboration.

You are spot on with your recommendations to documentation managers, I agree, but the key to a real working agile team is to involve all members of the team – writers included. It’s the first question I ask when I interview for a job, and I try not to work with or for companies who do not recognize this very crucial detail. The writers are part of the team, not the afterthought.

Thanks!

Virginia