Ellen Ferlazzo, of Sprezzatura Systems, took my rant on documentation seriously. Ellen says that if you do it right, you can deliver the documentation at the same time as the software. I was willing to give the writers an extra iteration. Rock on, Ellen!

Ron Jeffries’ “rant” about documentation in XP environments is perhaps less tongue in cheek than he meant! (See Manuals in XP). It is actually how I prefer to write user documentation, despite not working in a true XP environment. I find much truth in the old phrase “If you can’t teach it, it’s not designed well.” What quicker way can there be to find out if something is teachable than to write up task-oriented documentation? And as things are built or changed, the documentation is updated. I often update the documentation before the code!

Writers, by the way, hate being behind and blamed for shipping delays more than you might imagine! When the documentation doesn’t match the software, no one ever says “Those darned programmers! They made changes at the last minute again.” What’s heard is yet another excuse for ignoring documentation: “It’s always out of date anyway.” When writers are not part of the team, they are cut off from decisions and ignorant of changes. Usually interim releases are not distributed outside of the team, leaving the writers in the dark until far too late in the process. When they have questions about how something works, the programmers are often too busy to spend time with them because the documentation is not one of their priorities. Creating working code and testing it gets the attention, not the writers. Making documentation part of the team deliverables is a wonderful idea because it eliminates the “us and them” walls that so often develop.

In addition to user documentation, I also do user interface design and project management. It all tends to get wrapped together on small projects. Prior to reading anything about XP, I stumbled upon some very similar means of quickly creating good (usable) software in a small team environment. Later, a programmer I worked with in one group recommended that I read up on XP and I loved it.I’ve still not had the fortune to work in a true XP environment, but I hope to one day soon.

In the meantime, I thought my experience doing design and documentation side-by-side with the programmers might prove interesting to those thinking about bringing writers into their teams. It doesn’t fit the true XP model of interchangeable team members. Although familiar with programming languages, I am not a programmer. I’m like someone who understands a foreign language but can’t speak it. Also, in the environment where this worked best I was also the project manager, so I had 3 roles that no one else on the team had. I think you might look at that and say an expansion of the “interchangeable parts” metaphor might be that each team member has to be able to do more than one narrow function rather than being able to do all functions. A broader awareness of how changes can impact other things, including schedule commitments and work outside of the immediate area of change, is beneficial in terms of assessing trade-offs and benefits.

Project Background

Here’s an example of how I’ve worked to design and document side-by-side with programmers. In one situation, the client needed an inbound-planning application for their trucking company.A simplified description of the system is that various “stuff” was picked up from various shippers and brought to various terminals, called origin terminals. The stuff was then sent on to the “destination” terminal (the one which would deliver the stuff), where it was unloaded, reloaded onto smaller trucks, and finally delivered to its destination.

Planners at the “inbound” terminals needed to know what was coming in to them, where it needed to go (outbound), and how much of it there was (pieces and weight), so they could make a reasonable guess as to how much would fit on a single truck.In the existing system, two planners at each terminal worked with hard copies of the manifests. The client wanted to automate this to allow the planners to work online, thereby being able to handle more volume without having to hire more planners.

Initial Phase

The programmer and I had some sketchy initial requirements handed to us, along with some initial design “suggestions”, which consisted of about 15 different screens the planners were supposed to work through! One thing we knew was that planners worked under incredibly tight deadlines, at a fast and furious pace most of the time. I couldn’t imagine them taking the time to wander thru 15 different dialogs.

We read and absorbed what was given to us and started playing around on a piece of paper, with some potential ways of displaying what we thought they needed to see. Eventually, we moved to the computers. I know just enough of Microsoft DevStudio to create screens and simple prototypes and began laying out some of the screens we had sketched out. The programmer began by creating a set of test data.

User Documentation

The programmer then took over the screens and added the things I couldn’t, and started putting some functionality behind part of it so we could play with it. While he was doing that, I started pasting screen shots into a document and writing up task-oriented user documentation (which later turned into online help). Doing this allowed us to continually simplify the design and make forward progress on both the functionality of the system and the documentation. I would write up some task how-to’s only to discover that our initial design skipped a few steps. We would then work together, with me talking and pointing at the screen and the programmer quickly implementing changes. This was an iterative process: I would write while he would program functionality; one of us would discover something we needed to add or something that was awkward; we would both design. Then I would return to writing and he to programming and testing.

We spent two days on this and then sent the documentation, which was functioning as a user interface specification, to the client for review. The client was across the country so a demonstration of the software, which would have been even better, was not possible. As it was, though, the customer could read thru the task-oriented documentation, see screenshots and see how the planners would accomplish their tasks. As we continued to flesh out the functionality, both the code and the document were kept in sync. At some point, the programmer did travel back to the client site and present the software to a group of users. He worked one night shift with the planners to see how they currently did their job. It would have been even better had I been able to attend also, since I was essentially playing the user role on our development site, but that was not to be. We released an interim version for their IT department to play around with, pointing to the actual database for input and a test database for output. During another trip, the software was used at one terminal for one night, which pointed out a few more things that could be improved.


At one point, we all decided that it was “complete enough”. It had all of the functionality that was originally requested. Our design consisted of a single screen view with three sizable panes. They could concentrate on various tasks at different times by resizing things and could pop up an image of the manifest with a double-click if they suspected a data entry error or some other exceptional condition. This was an “extra” they found quite useful. They began deploying it, traveling from terminal to terminal to train the planners for a night or two.

This software was one of the pieces we developed that the customer was the most happy with in the long run. There was user-resistance, for sure. The planners were, for the most part, very unfamiliar with using computers for anything! But having a writer/designer work side by side with a programmer worked great in terms of delivering a complete package in the time frame expected.

Effects of Iterative Documentation

The iterative development process affected the document as well as the code. The document I wrote began as a specification, because I was ahead in functionality. That is, the tasks I was writing about were not functioning in the software at the time. As the development continued, it took less time for me to keep the document up to date (and often ahead) of the code. I was project managing about 6 other projects at the time, so I began spending less and less time on the project and documentation as the programmer continued implementation and testing.

We eventually turned it over to a different programmer to complete. He had my specifications documents and updated it himself at times as he added features. The document went thru a metamorphous and changed from specification to online help. Screen shots were removed at that point, but the task oriented how-to descriptions remained. Not only was this more useful than a button by button description, because it was oriented towards helping the planners get their job done, not what a button did in isolation, but it was up to date because it was the source – not the code!

Documentation as a Deliverable

At the end of Ron’s article he writes “An XP team with associated writers can deliver a documented product at most one iteration after code complete.” But, unless there are functionality and/or UI changes during the very final iteration, I think the documentation ought to be able to be completely in sync with the code. Of course, part of the testing needs to include “if you broke the documentation, it needs to get fixed just like code.” If the writer is part of the team, communicating this becomes much easier!

In my case, not only was the documentation not late or out of date, it affected quite positively the design of the software because it played the role of user for us as well, keeping us on track in terms of functionality and usability.

Copyright © 2002 Ellen Ferlazzo www.sprez.com