Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
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 the following:
Design and development artifacts (what was done, how it was done, and why it was done that way)
Planning, scheduling, and progress tracking (when things were done, how well they were done)
Responsibilities (who did what)
We don't 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're frequently lost over time.
Sometimes, for legal reasons, you have to create large amounts of documentation. Products like Together, which can take comments from source code files and generate documentation conforming to specified templates, can go a long way toward easing the pain. Keeping the documentation in the source code decreases the chances that it will get lost and increases the chances that it's up to date.
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 can capture. For example, the DBF task "Form a 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're programming in Java you can generate and capture Javadoc output).
Once we've decided what documentation to keep, the next problem is how to link it all together in a way that makes sense. Imagine that we were doing this manually: A chief programmer (CP) prints a copy of the DBF and BBF activities for his next iteration. He or she assigns a unique name or number to the iteration and writes it on the top of the printout. Next the chief programmer lists the name or ID of the feature or features included in that iteration on the printout. Then, to track progress, the CP writes the completion date next to each task as it's completed.
If we left enough space under each task we could also ask the chief programmer to write the names of the developers in the feature team and the names of any files produced as the result of each task. The printout becomes the integration point for all the documentation created during an iteration.
At this point you're probably ahead of me, thinking to yourself, "What if, instead of printing 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're 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 resulting iteration web pages "Chief Programmer Work Packages" or "Chief Programmer Work Folders."
Imagine that a chief programmer has identified the feature or group of features to be developed in the next iteration. He or she requests a new work folder for that iteration, giving the iteration a unique name or ID number. Next the CP 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 referenced documents").
The DBF task "Form a feature team" 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, and then 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's also published on the intranet. (We used to publish Javadoc as the final step in our regular, automated build process.)
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 overhead without a dedicated administrative assistant to do the data entry.)
If the team is using a version control system with a web front-end, we can even generate hyperlinks to the before-and-after versions of the source code files.
In our example, 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 might have been 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 to find requirements issues earlier.
I've deliberately left out details of how to implement the work folder; there are many ways to attack each part. Implementation details will also vary according to each team's/organization's project infrastructure.
For most teams wanting to try this out, it's sufficient to produce a very simple prototype at first. Remember that you won't 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.