Writing to Learn

 Posted by on Dec 8, 2009  Add comments
Dec 082009

“Writing is a form of thinking, whatever the subject,” says William Zinsser (Writing to Learn). If, as Zinsser says, learning to write well is critical to learning well, then agile team members might do well to work on their writing skills.

The entire results of software projects are writings. Whether the output is executable code, test scripts, requirements documents, training plans, or project status reports, they are all, in some fashion, writing. Writing is both a form of thinking and the results from that thinking—and unfortunately, technical education programs rarely focus on writing skills. Zinsser writes, “My hope was to demystify writing for the science types and to demystify science for the humanities types.” His working hypothesis is that “Writing and thinking and learning were the same process.”

Consider two of the long-standing problem areas in software development—requirements specification and code development. Requirements specifications are fraught with misunderstanding, a portion of which could be clarified by better writing. In his book, Exploring Requirements, Jerry Weinberg discusses sources of ambiguity. Weinberg asks classroom participants to recall and write down a question they were shown a few minutes before. He then lists at least 25 variations on the question that participants came up with and calls this phenomena “problem statement ambiguity.” This was a simple one sentence example. What are the possibilities for mis-interpretation in a 100-page requirements specification that must be read and interpreted by a 20-person development team? Better writing won’t completely solve the ambiguity problem, but it may reduce its size.

Anyone who has ever read code realizes that there are many ways to solve the same problem—some of them truly awful. Writing good code—code that is simple, straightforward, and easy to understand—is as much a “writing” skill as writing a coherent article or book.

Zinsser believes that good writing can make any subject interesting and available to a general audience. Take for example John McPhee’s book Assembling California, which delves into California’s earthquakes and other complex geology in a way that fascinates readers. Zinsser points out that good writing and good learning go together, “Writing organizes and clarifies our thoughts. Writing is how we think our way into a subject and make it our own.”

Writing is hard work. Sometimes we write about what we know. Sometimes we write about what we are thinking—to attempt to clarify that thinking. Zinsser,  “Ambiguity is noise. Redundancy is noise. Misuse of words is noise. Vagueness is noise. Jargon is noise. Pomposity is noise. Clutter is noise: all those unnecessary adjectives (“ongoing progress”), all those unnecessary prepositions draped onto verbs (“order up”), all those unnecessary phrases (“in a very real sense”). Information is your sacred product, and noise is its pollutant.” We are in the “Information” Technology business. We have to separate information from noise. Learning to write well should be on every agilist’s career development list.


Jim Highsmith

Jim Highsmith was the founding director of Cutter Consortium's Agile Product & Project Management practice.


  5 Responses to “Writing to Learn”

  1. […] Pro Tweets New blog post: Writing to Learn http://blog.cutter.com/2009/12/08/writing-to-learn/ cuttertweets – Tue 08 Dec 18:31 0 […]

  2. Thanks for the post Jim. I think the learning from writing you mention comes in two forms, but not everyone learns best by writing.

    It is true that for some, writing is an effective instrument to clear out noise in their own mind. The level of accuracy and precision in their writing will reflect the command they have achieved over a concept or topic.

    On the flip side, some people learn best from reading. Certainly, reading an elegant composition of thoughts that is both accurate and precise will accelerate their understanding.

    But i consider writing one of many potentially effective instruments to nurture and express thoughts.

  3. Writing is a useful tool, for sure.

    But let’s please beware of the trap that this leads us to. That writing (requirements, specifications, designs) is a substitute for code. Human language is inherently ambiguous and not up to the task of replacing code. Too many times have I seen projects led astray under the assumption that if “we just wrote more, better there’d be less ambiguity.”

    BTW the three best programmers I have worked with in my career, brilliant people all, were uniformly terrible writers. I am tempted to conclude that the skills required to write prose well are sufficiently distinct from writing code well as to be effectively orthogonal. Certainly, clear thinking and writing skill are uncorrelated — just check the articles in the op-ed page of your local newspaper. WIthout naming names, there is some beautiful prose in my hometown (Washington Post), with woefully inadequate logical argument.


  4. avatar

    Writing is clearly an important aspect of communicating our ideas. At the very core of the agile concepts is the importance of working with each other, ideally face-to-face; however, it is naive to think that all of our ideas can be done this way. There always be some correspondence that involves writing (e.g. emails, documents, etc.)

    Jim, Clearly you write a lot. Are there any resources for improving writing skills that stand out to you?

  5. avatar


    Everyone has a different style of writing, so much of the effort is finding one’s own style. A couple of resources: “On Writing Well,” by William Zinsser, “Writing to Learn,” also by Zinsser, “The Art of Creative Nonfiction,” by Lee Gutkind, “Writing for Story,” by Jon Franklin, and “Weinberg on Writing,” by Gerald Weinberg.


 Leave a Reply

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>