Where’s the forest?

August 24, 2010

Over on LinkedIn, the Agile Tech Writers group has been helping me deal with one of the biggest challenges Agile Development has presented so far – how do you document an entire software product when sprints are merely a small glimpse of the big picture?

We’re still getting our feet wet with Agile, but I have one project that is a brand new product, which I’ll call X here.  In our old development process, X would have a series of requirements documents for each feature, plus a master requirements document that I would use as my base.  The descriptions in these docs provide a starting point for my external research (our products support other third-party apps), which in turn help me develop the right questions to ask to fully document the new system. But in our current Agile process, I have no requirements. All I have now is an entry in a sprint back log for one of the Product X features.  I’m supposed to be documenting this feature with no idea how it fits into the product. I know there is a forest out there, but I am stuck on one branch of one tree.

Where do I begin? I am essentially writing inside out. How can I fully document a feature during a sprint when the rest of the product is still being developed?

Based on the comments received from the Agile Tech Writers LinkedIn Group, the problem, it seems, isn’t with my process, but may be with me.  I’m still trying to work the same way I’ve always worked while Agile has changed that model. The questions I used to ask my development team no longer apply. From David Farbey, I learned instead of asking very specific questions regarding the feature’s use, I should be asking questions geared toward understanding its implementation and the advantages it provides to users.

In a comment from Chris D., who said Agile opens doors, I realized it’s no longer enough to sit and wait for information to trickle down to me. Nor must I track it down. Rather, I should be getting involved in the development effort, looking for places to influence interface design and being what technical communicators have always tried to be – “a true customer advocate.” Anne Gentle wrote in a recent post that “Being an active member of the Agile team is crucial to a writer’s success.”

Toward this end, I contacted the Product X Development team and asked when their scrum meetings take place. I’ll show up, listen while looking for places where I can add to the discussion, even though it may be too early in the process, at least from a traditional perspective. But my confidence is returning. I have a UI background, so I can certainly influence decisions there.

David F. also reminded me of a key point in Agile development: “Developers do not code an entire product release in a sprint.”  Yet, here I am, trying to document all of Product X during a single feature sprint. Ideally, the information I write for this feature would be modular and ready for integration into the full product doc set at some later date. It’s okay if I don’t have the whole picture now. It’s even okay that I state during scrum meetings that I can produce only X-related conceptual topics during this sprint.

The point, I have learned (thanks to Sara, Julio, Pat, David, Kat, Maya, Verner, Larry, Chris, and Pramod), is that Agile can be flexible and therefore, so should I.



  1. Your problem seems to be quite common and i agree with you that it’s commonly caused by holding into old mental models.

    I’ve actually blogged about these problems, coincidentally using similar analogy as you did here:

  2. Hi Patty,

    Don’t kid yourself. Especially in Agile, it’s never too early to get in on scrums. If they’re developing code, you belong in the scrums so you can stay up to date on what’s happening. Keeping up on the changes is one of the most important things you can do, and scrum helps immensely.

    It’s really easy to think in a feature-centric way in Agile because the focus is on developing shippable code in each sprint (we call them iterations). It may help to plan your task-based documents and work on them in each sprint, and maybe after two or three sprints, you have a complete procedure that’s ready to be published. Or just plan on doing those documents in the sprint in which the task is being completed in the product.

    Good luck!

  3. Thanks, Ben. I agree; I’ve spent all week making a pest of myself, trying to invite myself to scrums. And the point you made in your second paragraph is also something I’ve struggled to accept – it’s okay to take more than one sprint to finish the documentation. I’ve been stuck on that.

  4. “Where do I begin? I am essentially writing inside out. How can I fully document a feature during a sprint when the rest of the product is still being developed?”

    I’ve been in that situation forever, and the UI Design Spec has been my saving throw. Our UI designer is excellent, and produces a design spec so extensive (and completely prior to the dev work) that I can create end-user docs prior to the work actually being done using his prototypes for screen shots. Typically, the Design Doc has been so well done that when I actually get the product, it usually matches about 80-90% of the time. So I’ve been creating prototype docs from the spec, and then cleanup after I get a working product.

    SDKs are a different story, of course. Those are always in motion up to the day of the release. Fortunately the APIs are autogenerated, so it’s primarily the tutorials and getting started guides that I have to update all the way to the end.

  5. There is nothing. No spec, not even a PowerPoint yet. All I have is a backlog item.

    Yet, I’ve been assigned to a sprint for this new product.

    All I can do at this time is write concepts for the sprint/feature. I can’t do any user tasks. I am beyond frustrated.

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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s

%d bloggers like this: