• Is Your Project Destined for Success or Doomed for Failure®
• The Anatomy of an Iteration
• Don Kranz's new column: DOC GEN-ing with Don

Is Your Project Destined for Success or Doomed for Failure?

by Jeff Cohen
Principal - ProcessExchange, Inc

For years I’ve been reminded that great minds think alike. What a great saying…but is it really true? Benjamin Franklin, Thomas Edison, Alexander Graham Bell, Walt Disney…the list goes on and on. It covers business and politics spanning hundreds of years. The real question is can you do what they did, and will it make you and your team successful too?

Frankly, I don’t know exactly how each one of them became so successful, but I do see one pattern. They never succeeded until they failed. They succeeded when they planned. They knew what they wanted to accomplish and nothing stopped them. They took small steps, learned from their mistakes, modified their behavior, and kept on trying until they reached their goal. For instance, Edison failed literally thousands of times when developing the incandescent bulb before he succeeded. He stuck to his plan, tracked what didn’t work, made modifications, and continued to execute until he succeeded.

They probably didn’t know everything they needed to know when they started a project, but they were experts at it when it was done. Business is very much that way today. One big advantage we have is the many easily accessible examples of success and failure to evaluate and learn about so that we can avoid some of the problems and implement best practices to improve our chances of success. Today, we should be able to capitalize on their hard-work and knowledge to use as a guide for success while reducing our risk of failure.

Recently I was talking to a customer that wanted to improve the way they did things. They have a process for development in place and believe that they follow it. They described how the team had some turn over and that retraining was an issue. I asked a simple question, “How long is an iteration for your team?” The answer was two months. Now I have difficulty remembering what I had for dinner two nights ago and I am only moderately successful at predicting what I will be doing two days from now, so I was having a difficult time understanding how a complex project, with thousands of variables, could possibly succeed using a two month iteration cycle.

So, how can we use “short” iterations as a tool to help us be successful? The answer, if not the implementation, is simple. It’s about discipline. It’s about investing the time necessary up front to do the planning and designing of your project. How often does management say we need a project done yesterday, “you start coding and I’ll go get the requirements?” I know that may sound a little extreme, but you’ve heard something like this before haven’t you? Maybe even experienced it first hand? It’s about itemizing the components of the project you will be working on, breaking them down into the smallest components that you can track and being disciplined and professional enough to repeat this with all your projects.

What has worked for others certainly can work here. Eli Goldratt in his book, The Goal, A Process of Ongoing Improvement, focuses on the Theory of Constraints. His premise is cut batch sizes and increase iterations to improve throughput. IT WORKS!!!

When you and your team become proficient at identifying components of the job which can be completed in two weeks instead of two months, it is possible for you to see exactly how far along your project is.

For the business it is about managing risk. Business units have deadlines, are they in competitive situations that demand quick response? If you constantly hear your people tell you that they are 80% done with the project and this goes on for months than it is time to rethink your batch sizes. Overly optimistic status reporting breeds resentment and hurts credibility.

For the developer, it is about completing tasks successfully, in a reasonable time, and being able to take the necessary steps do deliver a good product. People are much more confident about what they are doing, when the risk is low. When the tasks are small, people know what they have to do and are much more confident that they can complete the task. People want to do a good job. When the task is well defined and small, the risk is low, the people are confident, they will deliver a quality product.

When your customer or boss asks where you are at in the project would you benefit from confidently saying we are 63% complete and on budget? Does your staff understand that in today’s climate their jobs are on the line because so many companies are outsourcing projects half way across the world for one-fourth the cost because risk vs. costs aren’t adding up. In light of the current overseas outsourcing momentum it is more important than ever to be successful often and share your success with your management. What better way to do this than to have a biweekly status report that provides this precise statement of project completion and health?

Batch size reductions enable teams to experience success frequently and provide management with important status information stating exactly what percentage of the project is complete. Just think of the possibilities! Your boss is considering who runs the next. Where will they turn? Probably you if you have history of providing predictability in the delivery of your projects. How will you know you have this key status information? This month in Mac Felsing’s article you will learn more about how the team accumulates this information and how to report it.

By using short iterations and breaking the work into smaller units you will be able to:

1. Reduce and manage the risks associated with your project while they are still manageable.
   
   
2. Provide your customer with more accurate estimates of project completion.
   
   
3. Show your customer verifiable progress much sooner.
   
   
4. Have significantly greater chance of delivering a successful project (on time, within budget, with all of the requested features).
   

In other words, by adopting this method of using small batch sizes and short iterations, you will increase your chances of being successful with your projects. Your customers will be more satisfied, your credibility will increase, and you will start to see huge rewards for a relatively small investment in discipline.

A by product of this effort is your ability to take advantage of reporting tools which provide greater insight and more specific status information about your project(s) without placing excessive demands on your developers. We’ll talk more about that in our next issue.

Your focus on the small manageable components of your application will enable you and your team to provide higher quality applications, which are delivered as promised, and earn you the respect you’ve earned.

About the author:

Jeff Cohen is a principal and co-founder of ProcessExchange, Inc.  Jeff brings 20 years of sales and sales management experience at leading companies including ADP, IBM, WebGain (Symantec/BEA spin-off), TogetherSoft and Borland. Throughout his career, Jeff has worked effectively with C-level executives in IT at the enterprise level.

Jeff Cohen can be contacted at:
jeff@process-exchange.com

The Anatomy of an Iteration

By Mac Felsing, Principal Mentor & Methodologist

Iterating is critical to Agile project success
When using or planning agile projects iterations must be carefully defined and planned to ensure success. In this two-part article “The Anatomy of an Iteration” we will look at:

• Part I - How iterations apply to the agile development process
• Part II - Review best practices for implementing iterations as a project management tool
  

Applying iterations to agile development processes
Today, in any conversation about process, you probably hear or include the word iterative or iteration when describing the characteristics of a good process. For instance, the Unified Process is defined as being “iterative and incremental.” Feature Driven Development (FDD), eXtreme Programming (XP) and other agile processes talk about iterating throughout the development cycle, or having iterations.

Webster’s Dictionary defines the word, iteration, as:

1. the action or a process of iterating or repeating as
   
   
   1. a procedure in which repetition of a sequence of operations yields results successively closer to a desired result
      
      
   2. the repetition of a sequence of computer instructions a specified number of times or until a condition is met, or
      
      
2. one execution of a sequence of operations or instructions in an iteration

By the first definition, we see that any sequence of steps or events that can be repeated, can be considered to be an iteration. Even traditional waterfall processes can have iterations; they are just very long and very complex.

The one element that is left out of the dictionary definition is the element of time. When we talk about iterations in agile terms, we are talking about well-defined periods or blocks of time during which sequences of steps are performed per Webster’s second definition. In agile terms, the shorter the iteration is, the better it is. The duration of an iteration may vary from one organization or team to another, but we have found that an iteration length of two weeks works well.

Why is it better to do things in short iterations? The simple answer is that it is easier to manage risk over a shorter period of time. In other words, there is less chance of things going haywire in a short time frame. If they do, the issues can probably be dealt with more readily than if they have had a long period of time to get out of control. This is what makes using short iterations a very powerful project management tool.

Characteristics of a well-defined Iteration
Basic Composition of an Iteration

Figure 1 – Simple view of a single iteration

A key point is that an iteration, as defined here, is independent of any specific process. Best practices have taught that a manageable recipe for an iteration is composed of 3 basic parts:

• Kickoff
• Midpoint review
• Post-iteration review

Iteration activities produce two artifacts:

• The Iteration Plan
• The Iteration Report

Activities

Kickoff
The kickoff consists of listing the items of work to be performed and any milestones to be reached during the iteration. This artifact is the iteration plan. It can be a simple word document, a piece of paper, or a spreadsheet. At the kickoff, all of the involved parties are present. The iteration plan is reviewed and agreed to, any issues or potential risks are recorded, and the iteration can begin. The point of the iteration plan and review is to get everyone who is involved in the iteration to understand what is expected of them, and agree that, barring unforeseen complications, the work can be accomplished.

Mid-iteration review
In the middle of the iteration, we conduct a review. The purpose of the review is to adjust expectations with the developers, the stakeholders, and the end users of the system,

This is a quick status to verify that there are no surprises. This is usually conducted with the project manager, chief architect, feature leads and the customer or stakeholders. During this time we confirm what will be delivered and list any variances or issues. This is also the point in time we determine if there will be any additions or deletions to the iteration plan.

Post-Iteration review and sign-off
The goal for the Post-Iteration review is to demonstrate to the customer and stakeholders, what was accomplished during the iteration, highlight in issues or risks that were encountered, and provide feedback to the process itself (adaptive behavior). The customer or stakeholder can be shown what was built, and if appropriate may even be able to run or test it in order to validate its usability (customer value).

Artifacts

The artifacts mentioned here, may take on several forms, based on the methodology actually practiced. The important point is that this information is available and that it is used to manage the risk involved in producing the actual deliverables for the project. In the next installment, we will look at some of the variations on how the iteration artifacts may be embedded in a process. (And it may be called something else or be embedded in various methodologies) is put together.

Iteration Plan
The Iteration Plan is the list of features (functionality and artifacts) to be delivered in the iteration. It consists of the following:

1. New features from discovered or requested new requirements (must be approved and prioritized) +
2. Reworked features (errors discovered during test or deployment) + Unfinished features from previous iteration (variance) +
3. Unfinished features from previous iteration (variance) +
4. Features scheduled to be worked on

The first iteration for a project will usually only consist of the scheduled features. As the project progresses, new features or functionality will be discovered, or the end users or project stakeholders will identify new functionality that “must” be in the project. In addition, developers will make errors or run across issues (risks) that were not anticipated, and as code and artifacts are delivered, testing will uncover errors that must be corrected prior to delivery to the customer. All of these situations are taken into consideration in building an iteration plan.

Iteration Report
The Iteration Report is derived from the Iteration Plan. For each of the features or artifacts worked on it provides:

• The actual state or milestone reached,
• The reasons for any variance from expected results
• Any other issues encountered during the iteration.

It is an accurate report of the work completed and any exceptions that were encountered. Various statistics can be derived from the captured information, such as the “run rate” – number of features or functions delivered per iteration (useful for predicting the team’s ability to deliver the project on time), as well as other information management can use to make decisions about the project (risk management).

In addition, information about the processes used during the iteration (the steps used to produce the deliverables) is also recorded in the Iteration Report. This provides the team with feedback about the process itself (making the process self-correcting or adaptive). The team identifies what works and what needs to be changed (+s and deltas), and applies the changes to the process for the next iteration.

Review
In this installment we have looked at how iterations can be used in an agile process to manage risk (“Keep the batch sizes small!”). We have also looked at the composition of a well-defined iteration. Next issue we will examine how iterations are/can be used in some of the most popular processes – FDD, XP and UP and review their value as a project management tool.

Mac Felsing has over 20 years of experience managing and supporting project teams. He is an expert in the use of Object Modeling. He is a TogetherSoft Certified Trainer and a Coad Certified Mentor. His role with clients is to enable effective use of process and ensure that quality Architecture's are implemented.

Mac Felsing can be contacted at:
mac@process-exchange.com

DOC GEN-ing with Don

by Don Kranz
Dir of Research - ProcessExchange, Inc.

Welcome to what I hope will be a regular column in the Process Perspective newsletter, DOC GEN-ing with Don. I have been using Together to automate the production of documentation since 1995. Over the past 8 years I have produced hundreds of custom reports for the Together product. I feel the doc gen module of the Together product is one of it's strongest features. It allows me to put processes in place that produce documentation that matches the system it is written for, and is easy to produce, and has minimum impact on the process of producing the code. It is important to make sure that ALL of the team (Managers, Marketing, Sales, Clients Production, Analysts, and Developers) know what are the project goals, how they are getting there, and what to do once they've arrived. That is the reason documentation is core to a project's success.

Together ControlCenter has some extensive documentation templates that ship with the product. Having a good understanding of these templates can help you to create your own useful documentation. I am currently writing a book with Ron Norman, A Practical Guide to the Agile Unified Process. That book is due out early next year, but one of the key factors in making the unified process agile was heavily leveraging the documentation generator in TCC to produce the key documentation artifacts for the unified process. While the book focuses on the process we put in place, this series of articles details the tools we used to accelerate that process.

I look forward to sharing the APG2AUP document templates with you in great detail over several months. I hope this opens your eyes to the possibilities this fantastic tool can provide for you.


Sincerely,

Don Kranz
Dir of Research
ProcessExchange, Inc.
don@process-exchange.com

Introduction

Scenario

So here is the problem we want to solve how do we produce the following artifacts in the least intrusive manner possible? The Development Case, regular Iteration Plans, Vision and Supplementary Specification, business and technical Glossary, Software Architecture Document, Test Plans, User Support Materials, and mitigate risks in our Risk List.

We want to leverage information in the Use Case, Activity, Class, Sequence, Component, Deployment and Data Models to produce this documentation. In this case a picture will be worth several thousand words.

Finally, it would be nice to have one central online source for project information that the entire team and the client can reference through out the project life cycle.

What we want to do is use the standard ProjectReportFrames report template from Together as a basis for building our custom APG2AUP report template.

Standard Together Documentation

In our book, we build a project for Burritt Motors. The client wants to be kept informed of all progress on the project, and be able to view the system at the level of detail he is comfortable with. We can run the standard ProjectReportFrames template against that project and we get the following home page:

In the lower left frame we can select the subpackage burritt.up_itplan and we get the following page:

Custom Documentation

The templates that ship with Together are extensive and show us many options that are available working with all the diagrams, and their output. The problem with the generated documentation is that it is very technical and it assumes you know the underlying project structure. Remember our client? They want to be able to go to the level of detail they are comfortable with so we need to make the information more business palatable.

Here is our customized home page:

Notice the user can now select the Iteration Plan, rather than the subpackage burritt.up_itplan. They are the same thing technically, but now it is much more identifiable by the client. Selecting Iteration Plan in the left frame brings us to the following page:

The Improvements

Frames
The format of the frames has been altered along with the purpose for the frames existence. There is now a title bar frame at the top of the page. This will bring you back to the home page frames and provide other key hyperlinks that the project deems necessary. The frame on the left is now our menu frame. It provides the primary navigation through the project. The diagram and details frames are still there but the content generated for them will change.

Business Names
Notice the system now uses business names instead of technical names. The following business names have replaced their technical counter part:

Hyperlinking
Menu selections now update both the details and the diagram frame. The standard template only updates the details frame. Should the frames become unsynchronized due to older templates, there are now hyperlinks at the top of the diagram and details frames to synchronize them.

Navigation
A new menu system is available for navigation in the left frame. This replaces the confusing dual menu system that ships with the standard templates. The menu always corresponds to the information in the details and diagram frame. It also supplies a tree so you can back up to root documents.

Custom Details
As shown in the iteration plan, the details frame can now produce custom reports based on the stereotype of the object that produces this documentation.

Changing the Frames

Time to roll up our sleeves and begin creating our APG2AUP report template. The focus of this column is setting up our frames for our online documentation. Open the standard ProjectReportFrames template, then save it as APG2AUP.tpl. Now we have the entire standard reporting behavior available, and it will still run when a customized document is not called for. Look at the frames in this template and where they get generated.

Layout Your Frames
It is a good idea to first define what frames you want in your browser window, and what purpose they will serve. Before we define our frames, let's first look at the frames that ProjectReportFrames.tpl uses.

We are not sure of the source templates for these frames, yet. We will fill the source in description as we work on the contents of these frames. For now let's define the frames we want in our documentation.

Define Your Frames
Now that we know what the frames should like, it is time to define them. Open the APG2AUP document template (tpl). Select File | Properties… from the menu options. Next we need to select the FrameSet Structure tab to define how our frames are going to look. First change the layout of the ROOT frameset from columns to rows. For now, we are not going to change the frame names. This will allows us to continue the canned report usage, without worrying if the frame definitions mucked that up.

Select the frame contentsFrame, and rename it XcontentsFrame. We do this because we want to move the frame and docgen does not provide an easy means of doing this. Now add a new frame called contentsFrame as a ROW in the ROOT frameset. Enter the percentage size of 10 for this frame. The source file name expression should also be hard coded to “project-summary.html”, because that is what was originally looked for. Double check the definition of XcontentsFrame against our new contentsFrame. Make sure we haven’t forgotten anything. Once satisfied go ahead and delete the XcontentsFrame.

Now we need to move the summaryFrame, so start by renaming it to XsummaryFrame. Now add a column-based frameset to the ROOT frameset as a holder for the three remaining frames. The percentage size should be 90% to occupy the rest of the screen. Now add the summayFrame to this new frameset. A percentage size of 20% should be good. We want the source file name expression to remain findDocBySubjectSelector(“package-summary;summary”) for now. Check it against the original XsummaryFrame, and delete XsummaryFrame when you are convinced it has been recreated. You can also delete the frameset that contained XsummaryFrame.

Now the frameset containing the diagram and details needs to be moved, but together won’t let us do that so we need to add a new row-based frameset inside the column-based frameset we have defined. We’re going to be redefining diagramFrame and detailsFrame, so rename them XdiagramFrame and XdetailsFrame. Add the frame diagramFrame to the new row-based frameset we just created. This frame should occupy 40% of the column. The source file name expression remains findDocBySubjectSelector(“diagramChart”). This frame has an enable condition, which means it won’t be created if this condition is not met. Keep the condition of getDGOption(“includeDiagrams”)==“yes”. Which is only true if the Include diagrams option is checked on the Generate Documentation Using Template dialog. So we are giving users the option of not generating the diagram frame. When you are satisfied with the results you can delete the XdiagramFrame.

Now add the frame detailsFrame to the same row-based frameset as diagramFrame. This frame should occupy 60% of the column. Populate the frame using the source file name expression – findDocBySubjectSelector(“”). XdetailsFrame can be deleted when you have all the information in detailsFrame. The only thing left to do is to test this and see if it works. Save the template, run it, and look at the results. When you run the report, make sure you use the scope current package with subpackages.

Note that the way together is currently set up, we need to build our frames top to bottom, left to right.

Bonus Topic: Class Diagrams vs Packages

Just for grins and giggles let’s change the settings on the generate documentation dialog. Specify a scope of Current diagram instead of Current package with sub-packages. Run the report and see what happens. The results look very different. The reason is there is a subtle difference between the diagram for a package and the package itself. The data controls within doc gen also help to blur the line more. This is a topic I could spend an entire hour on all by itself. Suffice it to say, you want to do your doc gening on the class diagrams associated with a package, and not the packages. It is the class diagrams that save all the data you input into Together ControlCenter^®. The reports in this example do not do that – yet.

Summary

In the inaugural version of this column we provided an overview of the documentation project ahead of us. This issue concentrated on setting up the frame presentation for our online documentation. Finally we tossed in some food for thought on whether or not you should generate on packages or class diagrams. In the next issue, we'll start changing the contents of one the frames we just created.

Don Kranz has over 20 years of software development experience. He has focused his career on improving the speed of development and quality of product for system teams. He is a TogetherSoft Certified Trainer and a Coad Certified Mentor. His role with clients is to ensure the proper resources are made available to provide the desired solutions.

Don Kranz can be contacted at:
don@process-exchange.com