Dear Friend,

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.

Have fun

Steve

---

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:

1. design and development artifacts (what was done, how was it done, and why was it done that way)
2. planning, scheduling and progress tracking (when were things done, how well were they done ).
3. 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 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 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 Referenced Documents).

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 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 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.

References