January 27, 2010

Agile Tenet #11 – Self Organizing Teams

Filed under: Uncategorized — heratech @ 9:24 am
Tags: , , ,

Number elevenEleventh in a series of posts examining the Twelve Principles of Agile Software and how each of these tenets can (or can’t) be applied or adapted to technical writing.


The best architectures, requirements, and designs emerge from self-organizing teams.

Who is more familiar with the code base – management or the developers who actually wrote the code? I can hear you thinking “Duh, the developers!” Of course.

Who is more familiar with the documentation – management or the writers who spend their day researching, writing, and organizing the content? Again, the answer seems a little bit obvious, doesn’t it?

And yet how many times have we experienced managers trying to do our jobs when they haven’t got the foggiest idea what our work actually entails? I’ve worked at a variety of jobs through the years, and I have learned to appreciate a manager who has come up through the ranks. Managers who started their careers as workers understand the issues that their employees are dealing with. And the wise manager knows when to get out of the way and let their teams go to work.

As you might guess, I’m rather fond of this particular tenet. Nothing irritates me more than a manager who doesn’t trust me to do my job without their constant supervision and input. Who knows my writing process better than I do? I’ve spent years learning and honing my craft, and over the years I’ve learned what works for me and what doesn’t work.

Donald Murray wrote about the writer’s toolbox. His writing books were full of different skills and techniques that his students and readers could add to their own writing toolboxes. You might pull out one technique for a particular project, then put it away and not use it for a very long time. Some people just sit down and start writing. Others need to do research, conduct interviews, take notes, brainstorm, write outlines, conduct interviews, or any number of other techniques. Our brains all work differently, we all process information differently, and we all work differently. Thinking that one writer’s process is the exactly the same as any other is a mistake that non-writers (and even writers) can make all too often.

If one person knows best how they work, wouldn’t it also make sense that the members of a team would know best how their team functions? If you’ve hired motivated individuals (you have hired motivated individuals, haven’t you?) you should be able to step back and let the team run itself.

And it has been interesting watching this tenet in action in our Scrum teams. Rather than have a manager impose structure and order from the outside, in Agile the ScrumMaster coaches the team, but lets them provide their own structure and order. The product owner writes the user stories and assigns priorities, but the teams decide which stories they will tackle in any given Sprint. The team decides amongst themselves which developers will tackle which stories.

I know that some people are uncomfortable making their own decisions. I’ve seen it manifest in everything from students who got stressed out when asked to provide their own opinion on a test (this wasn’t in my notes!) to coworkers who couldn’t make their own decisions without polling everyone in the office about what they should do. But these aren’t the sorts of people who would thrive in an Agile environment, they are most comfortable in an office hierarchy, where management tells them what to do and how to do it.

I wonder if I’m so comfortable with this self-directed approach because I went to Montessori school as a child? Reading over the Wikipedia entry, I noticed this passage:

Applying this method involves the teacher in viewing the child as having an inner natural guidance for its own perfect self-directed development. The role of the teacher is therefore to watch over the environment to remove any obstacles that would interfere with this natural development.

Sounds a bit like a ScrumMaster, whose job it is to coach and remove impediments, doesn’t it? Montessori is about providing an environment for learning. And I think that Agile is about providing an environment where productive work can occur.

December 22, 2009

Agile Tenet #3 – Deliver Frequently

Filed under: Uncategorized — heratech @ 8:09 am
Tags: , , ,

Number three Third in a series of posts examining the Twelve Principles of Agile Software and how each of these tenets can (or can’t) be applied or adapted to technical writing.


Deliver working software frequently, from a couple of weeks to a couple of months, with a preference to the shorter timescale.

When I was working in a Waterfall development environment my writing process was long and drawn out, similar to writing a novel. I once worked a solid 18 months on a single release. The User’s Guide was almost completely revised, and weighed in at 450 pages by the time I was done. For that particular release I did nothing for three solid months but read through the hundreds of pages of specifications for the release, taking notes along the way of new applications being added to our application suite and new features. Then I struggled with my outline for several weeks, trying to figure out a structure that would accommodate the new material. I was writing notes and draft topics the whole time, but the new release had so many different applications, that it was hard to find a structure that would fit the wide range of new features. Once I settled on a structure, I spent almost a year playing with the software builds, exploring the new features, interviewing a dozen different product managers, writing and revising before the software and doc was actually released.

In Write to Learn Donald Murray describes techniques used by all writers (Collect, Focus, Order, Draft, and Clarify), and urges his students to adapt them to their needs. And that list describes my writing process pretty well. My technical writing textbook, How to Communicate Technical Information, breaks the writing process down to just Planning, Writing, and Revising. However you define your writing process, in an Agile environment it is severely compressed.

I’ve heard TWs estimate that they only spend between 25% to 40% of their time actually writing, with the rest of their time taken up with e-mail, meetings, planning, research, and other non-writing tasks. When you’re writing documentation in an Agile environment, your process is no longer the long slow march towards a major release. In an Agile environment, you’ve got to be much more efficient. You have much less time to think about what you’re going to write, because if you are going to deliver content by the end of the Sprint, you need to stay focused on tasks that support the writing.

I’ve already written about how I use modular writing, and some of the techniques I use for being ready to publish at all times. Making the switch from the long cycles of Waterfall to shorter Agile Sprints has not been as big a shift for me as it might be for writers who were not used to delivering information in small chunks. But even so, I’ve had to learn to let go of my own expectations for the documentation. There has always been a gap between the documentation that I want to deliver and the documentation that I can deliver in a given timeframe. With a shorter timeframe, that gap widens considerably. (Thank goodness tenet #9 is Attention to Excellence!)

It seems to me that one of the tricks of being an Agile technical writer is to be less like the novelist and more like a journalist on deadline, trying to scoop the competition with a big story. Journalists are continuously writing because they have to deliver content, be it a daily newspaper, news weekly, or monthly magazine. But unlike a journalist, the Agile TW can always go back and revise what they’ve written in a later iteration.

Deliver documentation frequently, from a couple of weeks to a couple of months, with a preference to the shorter timescale and delivery of smaller chunks of information.

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.