The Coad Letter: Modeling and Design Edition, Issue 72, Chief Programmer Work Folders
Over the last couple of years many software development teams have started
using internet technologies to build project repositories. Imagine the possibilities
of combining products like Together, tools like Javadoc, web-enabled version
control systems, calendars, discussion areas, databases and directory servers.
This powerful combination provides a development team plenty of opportunities
to capture, generate and link documents and other artifacts created throughout
a project. The question that the technology does not answer is exactly what
documents to create, capture and how best to link it all together. Therefore,
this month, a short set of notes exploring the recording of artifacts produced
during the two engine room processes of Feature Driven Development, Design
By Feature (DBF) and Build By Feature (BBF).
For an introduction to Feature Driven Development, please see,
Coad Letter #70.
Chief Programmer Work Folders
The Design By Feature and Build By Feature activities form the construction
engine room of the Feature Driven Development process.
Each of the two activities includes a number of tasks to be performed by
the chief programmer or the feature team as a whole.
|The Design By Feature activity contains seven
tasks, as follows
- Form a Feature Team
- Domain Walkthrough
- Study the Referenced Documents
- Build a Sequence Diagram
- Write Class and Method Prologs
- Design Inspection
- Log Design Inspection Action Items
|The Build By Feature activity contains five
tasks, as follows
- Implement Classes and Methods
- Code Inspection
- Log Code Inspection Action Items
- Unit Test
- Develop a Team Model
- Check in and Promote to the Build Process
Documenting the Engine Room
How much and what sort of documentation should we create and keep for each
iteration through the DBF and BBF activities?
The information captured during any project includes:
- design and development artifacts (what was done, how was it done, and
why was it done that way)
- planning, scheduling and progress tracking (when were things done,
how well were they done ).
- responsibilities (who did what).
We do not want to force developers to spend significant time creating unnecessarily
large volumes of design documentation and project plans; many of us
working on internet time can no longer afford the luxury of the time required
and few developers relish the task. The resulting documents are also hard
to maintain, seldom fully read and understood, and they are
frequently lost over time.
Sometimes, for legal reasons, you have to create large amounts of documentation.
Products, like Together, that can take comments from source code files and
generate documentation conforming to specified templates, can go a long way
to easing the pain. Keeping the documentation in the source code decreases
the chances that it will get lost and increases the chances that it is up
The documentation that we create and keep for each DBF/BBF iteration is
defined by the tasks; each of the tasks in the DBF, BBF activities produces
an output of some sort that we could capture. For example, the DBF task
Form the Feature Team results in a list of developers and the BBF task
Implement Classes and Methods obviously results in a set of updated
source code files (and if you are programming in Java you can generate and
capture Javadoc output).
Once we have decided what documentation to keep, the next problem is how
to link it all together in a way that makes sense. Imagine we were doing
this manually: A Chief Programmer prints out a copy of the DBF and BBF activities
for his next iteration. He assigns a unique name or number to the iteration
and writes it on the top of the print out. Next the Chief Programmer lists
the name or id of the feature or features included in that iteration on the
print out. Then to track progress the Chief Programmer writes the completion
date next to each task as it is completed.
If we left enough space under each task we could also ask the chief programmer
to write down the names of the developers in the feature team and the names
of any files produced as the result of each task. The print out becomes the
integration point for all the documentation created during an iteration.
At this point you are probably ahead of me and thinking to yourself, "What
if, instead of printing out a copy of the DBF and BBF activities, we used
an HTML form instead?". Yes - and with a little work we can add some intelligence
to reduce the overhead on the chief programmer - especially if we are already
using our project intranet to Track by Feature (see
Coad Letter #70 for more details on Track By Feature). This is exactly
what we did on one project; we called the iteration web pages, Chief Programmer
Work Packages or Chief Programmer Work Folders.
Imagine, a Chief Programmer has identified the feature or group of features
to be developed in the next iteration. He requests a new Work Folder for that
iteration, giving the iteration a unique name or id number. Next the Chief
Programmer specifies the features to be implemented in the iteration. If
we already have a table of features for the project, the Work Folder can
automatically display the specified features' details. If each feature in
our project table is hyperlinked to the relevant use cases, functional specification
sections or domain walkthrough notes, the Work Folder can also automatically
list the relevant documents to study in the third task of DBF (Study the
The DBF Form the Feature Team task requires the Chief Programmer
to remember or look up the owners of the classes involved in the iteration.
If we already have a table on our project intranet relating developers to
the classes they own, the Work Folder can accept the names of the classes
involved, look up and automatically list the developers required in the feature
team. We could even extend this to automatically include hyperlinks to the
current version of the Javadoc output (or documentation generated by Together
or both) for the classes involved if that is also published on the intranet
(we used to publish Javadoc as the final step in our regular, automated build
Next we ensure that each task's outputs are captured in a form that can
be published on the project intranet. Then the feature team can publish outputs
and add hyperlinks to the Work Folder as they complete each task. These outputs
could include notes from the domain walkthrough task and summaries
of the inspection results (details of the inspection such as the list of
defects found may be too much of an overhead without a dedicated admin. to
do the data entry).
If the team is using a version control system with a web front-end, then
we can even generate hyperlinks to the before and after versions of
the source code files.
Here's an annotated view of an actual work package (slightly modified to
make it anonymous and easier to read):
The project management team appreciated the details and information contained
in the Work Folders. The Chief Programmers and developers also liked them;
when working in two or three feature teams concurrently, they could look
at the Work Folder and immediately see how far the team were through the
iteration. Also all the relevant information for that iteration was immediately
accessible from one place - a great convenience tool.
Looking at the contents of the work folder, you can identify much of the
content that would traditionally be part of a design specification document
for a module. Such a document would typically be written by one or two developers
and extensively reviewed before coding started. In the meantime, the requirements
might have changed and the authors forced to make major modifications to
the document before submitting it for review again.
Instead, the feature team members have created much of the content of the
Work Folder together as they worked through the DBF/BBF activities. This
helps reduce the number of design errors and spreads the responsibility for
the design across the team. Also, the fine granularity of the iterations spreads
the documentation load over time. Reviews are done earlier and in smaller
chunks helping find requirements issues earlier.
I've deliberately left out details of how to implement the Work Folder;
there are a numerous ways to attack each part. Implementation details will
also vary according to each teams/organizations project infrastructure.
For most teams wanting to try this out, it is sufficient to produce a
very simple prototype at first. Remember that you will not be thanked by
your clients for producing the ultimate, web-enabled Chief Programmer Work
Folder system - your clients want the system they asked you to build.
The conclusion? Chief Programmer Work Folders are a simple, effective solution
for document weary development teams.
Coad, De Luca, Lefebrve, Chapter 6, Java Modeling in Color with
UML, Prentice Hall 1999 (