November 22, 2009

November STC Meeting – Documentation in an Agile Environment

Filed under: Uncategorized — heratech @ 3:17 pm
Tags: , ,

Last Wednesday night I attended the monthly Boston STC meeting.  The topic was “Documentation in an Agile Environment.”  The discussion panel consisted of two writers, a doc manager, and a QA tester.  At the beginning of the evening the moderator polled the audience and the vast majority of the audience was not working in an Agile environment. From the questions they were asking, it seemed that many of them were completely new to the concept of Agile programming.

During the question and answer period at the end, one of the older members of the audience asked a question about writing process.  She said, “It seems like you start with the outline.  When do you have time to do the brainstorming?”  That struck me as an odd question.  The way she asked seemed to imply that an outline was NOT where you start.  I got the feeling that she thought the proper process for writing was to brainstorm, then write an outline, then start writing.  It made me think a lot about my own writing process and how it might be vastly different from writers of a previous generation.

I learned the craft of writing at the University of New Hampshire. My four years at Phillips Exeter Academy had given me a solid foundation as a writer, but it was at UNH where I developed an appreciation for the mechanics of writing.  And that was probably due to the influence of Donald Murray on the UNH English department.

My freshman composition class used his Write to Learn as our writing text.  And it was through this book that I was introduced to the idea of the writer’s toolbox.  A writer can have many different tools, some that they use all the time, and some that they may only pull out for particular projects.  There is no One Right Way To Write.  And that’s an important thing to remember.

One of the panelists answered her by saying that when you’re doing Agile writing, you work during the sprint to document the feature, then during the next sprint you work on the next feature. “You write it.  It’s done.  You don’t come back to it.”  Which got me to wondering, when do you have time to write conceptual information?  Almost everywhere I’ve worked, the procedures (“how to”) are adequately documented, but what is lacking is information about “why” you use the feature and the “when” or best practice information.  I’ve spent most of my writing career trying to fill these holes.  And it takes time to be able to determine what needs to be written in the overviews and develop enough customer and product knowledge to be able to write examples and best practices.

Donald Murray also wrote the Craft of Revision which also holds a spot on my bookshelf.  While I don’t write nearly the number of revisions that Murray did (he was almost a compulsive rewriter) I do often return to things that I’ve written, give them a re-read and revise my work.  I don’t often do full fledged revisions, but there are often small improvements that can be made. Especially when there is content that was written under deadline pressure where I didn’t understand a feature well enough to write a solid overview.  Or when I have learned something new about how customers are using our product and can add real-world examples. 

I don’t think I’ll be able to write something and then never come back to it.  Luckily there will be sprints when the developers are working on architecture stories or something else that happens behind the scenes and doesn’t need user documentation, and I’ll be able to go back and tweak my documentation.

One of the things I’ve been struggling with is how my writing style fits into an Agile development process.  I’ll be writing more about that in upcoming posts.


Post Script

In writing this post I learned that Donald Murray had died in 2006.  While I was never his student, I learned a great deal from his books, and read his column in the Boston Globe for many years.  It is because of Donald Murray that I think of writing as a craft, and myself as a craftsman.  I also discovered this wonderful appreciation of Donald Murray.

Blog at WordPress.com.