The Zühlke Software Development Process

Zühlke Engineering www.zuehlke.com

The Zühlke Software Development Process / Version 1 Page 1 of 24

The Zühlke Software Development Process

A Zühlke Engineering White Paper

Michael Hirsch 21-January-2003

Version 1

Table of Contents

1. Introduction............................................................................................................................................2 1.1 Company Background ...............................................................................................................2 1.2 The History of Software Development at Zühlke.......................................................................2 1.3 Our Business Model for Software Engineering..........................................................................2

2. An Overview of the Rational Unified Process .......................................................................................3 2.1 Fundamentals of RUP ...............................................................................................................3 2.2 Process Overview......................................................................................................................4 2.3 Phases .......................................................................................................................................6 2.4 Disciplines..................................................................................................................................8

3. Applying RUP for Contract Development Work ....................................................................................9 3.1 Assumptions and Policies..........................................................................................................9 3.2 Project Scope ..........................................................................................................................11 3.3 Customer Involvement.............................................................................................................12 3.4 Typical Artefacts ......................................................................................................................14

4. Forms of Contracts..............................................................................................................................18 4.1 Inception Phase Contract ........................................................................................................18 4.2 Elaboration Phase Contract.....................................................................................................19 4.3 Construction and Transition Phase Contract...........................................................................19 4.4 Maintenance Contracts............................................................................................................20

5. Supporting Infrastructure and Technical Expertise .............................................................................20 5.1 Software Engineering Process Group .....................................................................................20 5.2 Development Tools..................................................................................................................21 5.3 Software Development Staff ....................................................................................................22

6. Conclusions.........................................................................................................................................22 7. Appendix: References........................................................................................................................23 8. Appendix: Questions to Ask your Software Contractor......................................................................23 9. Appendix: Contact Information...........................................................................................................24 10. Appendix: History of Changes............................................................................................................24



1. Introduction

This paper describes the software development process used for contractual software develop-ment work done at Zühlke Engineering, and how it affects the cooperation with our customers within projects. The paper is aimed primarily at customers, and potential customers, who want to evaluate us as a contractor for software development work. The reader is assumed to be familiar with basic concepts of software project management and software development processes.

1.1 Company Background

Zühlke Engineering is an independent engineering company with offices in Zurich, Basel, Frankfurt and London. Our main business is consulting and development work involving software engineer-ing, electronical engineering and mechanical engineering. The company was founded in 1968 to offer mechanical design services to the Swiss machine and precision engineering industries. Elec-tronical engineering was added in 1970, software development in 1974. Today we employ over 200 engineers worldwide; of these, about 100 are software engineers.

1.2 The History of Software Development at Zühlke

Software development at Zühlke began in 1974 with developing firmware for embedded systems designed by our electronical engineers. It was soon expanded to include development of industrial control systems, resource planning systems, and various industrial engineering and design tools. In the time from 1980 to 1991 we did most software development work with SA/SD, Pascal, Ada, C and Assembler on VAX/VMS, PCs, and embedded systems.

In the early 1990's it became obvious to us that SA/SD and structured programming did not scale well for large and complex software systems. As a result, we started a transition to object oriented software development in late 1992, which was completed by early 1995. Since then, we are a "100% OO shop". The year 1992 was a turning point for software development at Zühlke in yet an-other way; we started offering our software engineering services to the banking and insurance in-dustries. Today about 40% of our revenues from software engineering come from the financial and insurance sector, the other 60% are from industry, telecom, and public services.

When we switched to OO development in 1992, we initially used the Booch OOA/OOD method and C++. In 1996 we did a few projects in Smalltalk. Though due to the declining demand for Smalltalk and the rise of demand for Java we decided to focus on Java and C++ in 1997, which is still the case today, with the addition of C#. Also in 1997 we switched to the UML.

With the growing size and complexity of software development projects the need for an organized process became apparent. Like many other companies, we defined, documented and refined our own software development process. This process was based on the waterfall model. There were two major problems with this process: First, it was very hard to accommodate frequent change re-quests. Second, many customers (and ourselves ) were very uncomfortable with analysis and de-sign phases taking months and seeing no executable software during that time.

Because of this we began investigating iterative processes in 1996, and replaced our own process with the "Rational Objectory Process" (ROP) in 1997. Since then ROP was renamed into RUP ("Rational Unified Process") and upgraded several times. Currently we are using RUP Version 2002. Our experiences with iterative development in general and RUP in particular are very posi-tive. Today, all significant software development work in our company is done with RUP.

1.3 Our Business Model for Software Engineering

Today we are offering the following software engineering services to our customers:



• Contractual software development work. We would develop a software system (or part of a larger system) according to specifications provided by the customer. We handle everything from software project management to analysis and design, implementation, testing, and pack-aging. The rest of this paper is about this type of service.

• Coaching and mentoring. We provide one or more consultants who coach and mentor the cus-tomers software development team in one or more of the following areas: software project management, requirements engineering, OOA/OOD, UML, RUP, software architecture, OO programming with C++ /Java/C#, and configuration & change management.

• Training in OO technologies, methods, processes, and programming languages.

• Development support. We provide one or more qualified software engineers, who work tempo-rarily for a customer. Project management is done by the customer, and therefore the ultimate responsibility for success or failure of the project is with the customer.

A fundamental assumption of our business model is that we contribute software engineering knowhow to a project, and the customer contributes domain knowhow. Since we are active in a wide range of industries, there is no way we can be experts in all domains. What we can and actu-ally do provide is expertise in requirements engineering, ie. in elicitating, documenting and manag-ing requirements. The broad range of industries we are active in has an interesting side effect. Quite often reusing a proven solution from one industry in another industry leads to innovative ideas and ultimately systems.

2. An Overview of the Rational Unified Process

As already mentioned in the introduction, we are using RUP (or it's predecessor, ROP) for all con-tractual software development work since 1997. Since then we have completed over 20 projects1 with RUP and learned how to apply it well for contractual software development work. If you are al-ready familiar with RUP, you may safely skip this chapter.

RUP is a product of Rational Inc. (www.rational.com) , which requires a license agreement. It is documented in the form of a set of HTML documents, which can be installed on a PC or on an intranet webserver. As of RUP Version 2002, the online documentation comprises over 2000 HTML documents. The rest of this chapter gives an overview of RUP. The next section ("Applying RUP for Contract Development Work") describes how we apply RUP in our customer projects.

2.1 Fundamentals of RUP

RUP is a software development process specifically designed for object oriented development, it encompasses all activities in a typical software development project. Experienced OO developers typically become proficient in RUP in a few weeks time. RUP is scalable from small projects with 2 or 3 developers to projects of any size.

RUP is based on a small number of software engineering best practices, which have proven to be successful in practice over and over again. These practices are:

• Iterative Development Projects are divided into a series of so called “iterations”, where every iteration — even the very first one — delivers an executable release with a subset of the functionality of the final system. Every iteration adds functionality to the system, until all fea-tures are complete and of sufficient quality. Most projects have between 6 and 12 iterations, where an iteration may range from two weeks (on a very small project) up to 3 months (on a very large project). There are a number of advantages of iterative development over the tradi-tional waterfall model. First, architectural and design problems are discovered much earlier,

1 This numer includes only projects where we acted as software contractor with full responsibilty for delivery. In addition to

that, we provided RUP related coaching and mentoring for another 40+ projects of our customers.



because software integration already starts in the first iteration ; corrections can be made be-fore much effort is spent on implementing a faulty design. Second, user feedback can be ob-tained as soon as the first iteration is completed. Third, it is easier to accomodate scope changes compared to the waterfall model, because there is always a stable software base upon which to base the changes.

• Requirements Management Requirements Management is a systematic approach to elicit-ing, organising, and documenting the changing requirements of a software system. Experi-ence has shown time and again that lack of systematic requirements management is one the most common reasons for project failures.

• Component Architectures The term "component architecture", as used by RUP, means any architecture where the overall system is broken down into well-defined components with a clearly specified interface and an implementation which is hidden from the user of the compo-nent. Good component architectures strive to minimize dependencies between components. Component architectures help to reduce the overall complexity of systems, which in turn re-duces the likelihood of design and implementation errors. Unbound complexity is another very common reason why projects fail.

• Visual Modeling RUP makes heavy use of the UML for visual representations of the systems architecture, its design, its use cases, and so on. Diagrams are a proven technique to provide orientation in complex systems. Every engineering discipline has its own set of diagrams for this reason, be it electrical engineering (wiring diagrams), mechanical engineering (design blueprints), or civil engineering. Without some kind of diagrammatic overview, it is impossible to maintain an overview of large software systems with hundreds of thousands of lines of code.

• Continous Verification of Quality RUP places heavy emphasis on extensive testing, includ-ing frequent regression testing. One might argue that with all of the careful requirements man-agement, employment of component architectures and visual modeling, and so on, testing shouldn't be all that important. However, practice has shown the contrary. Regardless how sophisticated the construction process is, some faults will always go unnoticed without testing. Testing is an integral part of every iteration, so the system is tested over and over again, which increases chances that nasty bugs get uncovered before delivery. Because testing is done so frequently, RUP strongly recommends using test automation to the greatest extent possible.

• Change Control With multiple iterations, multiple developers and (possibly) multiple software configurations, it is absolutely essential to keep track of who changed what, when and why. In RUP, change control applies not only to the source code, but to all artefacts of a project, in-cluding planning documents, requirements documents, test cases, and so forth.

The six best practices outlined above can be applied by every software development project, re-gardless whether RUP is used or not. However, RUP provides a multitude of guidance in how to successfully apply these best practices in real world projects.

2.2 Process Overview

The most important elements of RUP are (see figure 1 below):

• Phases are shown on the top horizontal axis. The four phases of RUP are called Inception, Elaboration, Construction and Transition.

• Iterations are shown on the bottom horizontal axis. Within an iteration all relevant disciplines are executed, resulting in an executable system. Number and duration of iterations are pro-jectspecific.

• Disciplines are shown on the left vertical axis. A discipline is a set of interrelated activities to achieve a certain result. In figure 1 below, the relative intensity of a discipline over time is indi-



cated by the height of the associated curve. As is to be expected, the Requirements and Analysis & Design disciplines are more intense in the early phases of a project, whereas the Deployment discipline is more intense towards the end of a project. The important distinction to the waterfall model is, however, that within a single iteration more or less all disciplines are executed, even though the relative amount of work spent on each discipline changes from it-eration to iteration.

Disciplines

Business Modeling

Requirements

Deployment

Implementation

Analysis & Design

Test

Configuration & Change MgmntProject Management

Environment

Organization along time

Organization along content

Figure 1 — RUP Overview

The following elements are not shown in figure 1 above, but are nevertheless very important:

• Artefacts An artefact is any kind of work product produced by a project, such as plans, guidelines, designs, or source code. RUP defines almost 100 artefacts, however, typical pro-jects use only a subset of these.

• Roles A role is a particular job description in a project, such as system architect, project manager, tester, implementer, and so on. One person may fill multiple roles, and one role may be executed by more than one person.

• Guidelines A guideline is a brief description of how an activity should be performed or how an artefact should be created. There are over 100 guidelines with detailed and practical ad-vice.

• Concepts provide background information on fundamental software engineering techniques and methods used in RUP, such as use case modeling, object modeling, software build strategies, project planning strategies, and so on.

RUP is much more than just a phase model for project managers. It contains a wealth of practical advice on many areas of software construction, from requirements engineering to coding practices. This makes RUP useful not only for project managers, but for software developers too. Because of this, there are very few objections from software developers when indroducing RUP compared to other more management centered processes.



2.3 Phases

Like every software development process, RUP defines a number of phases which are concluded by major milestones. The phases and milestones of RUP are:

• Inception phase In this phase the scope of the project is defined and a business plan is es-tablished. Concluded with the Lifecycle Objectives Milestone (LOC).

• Elaboration phase In this phase the architecture is demonstrated and detailed requirements are defined. A high fidelity project plan for the construction and transition phases is estab-lished. Concluded with the Lifecycle Architecture Milestone (LCA).

• Construction phase In this phase the software is brought from an executable architectural baseline to the point at which it is ready to be transitioned to the user community. The bulk of the development work is done in this phase. Concluded with the Initial Operational Capabili-ties Milestone (IOC).

• Transition phase The last phase of the process, in which the software is turned over to the user community. This phase typically includes beta testing. Concluded with the Product Re-lease Milestone (PR).

Each phase is divided into one or more iterations. Number and duration of iterations are project specific. The following table gives an overview of the typical distribution of effort and calendar time among phases.

Phase Milstone Effort Schedule # of Iterations

Inception LCO (Lifecycle Objectives) 5 % 10% 1 to 2

Elaboration LCA (Lifecycle Architecture) 20% 30% 2 to 4

Construction IOC (Initial Operational Capabilities) 65% 50% 3 to 6

Transition PR (Product Releases) 10% 10% 1 to 3

Table 1 — Phases of RUP

2.3.1 Inception Phase

The most important goal of the inception phase is to achieve concurrence among all stakeholders on the lifecycle objectives for the project. Specific objectives are:

• Establishing the scope of the project, i.e. what is intended to be in the product and what is not

• Come up with the critical requirements

• Come up with at least one candidate architecture

• On large projects, demonstrate the candidate architecture

• Perform an initial risk assessment

• Estimating the overall cost and schedule for the entire project, and more detailed estimates for the elaboration phase that will immediately follow

The most important deliverables of the inception phase are:

• A vision document which contains a general vision of the core project's requirements, key fea-tures, main constraints

• A draft of the use case model (20% complete)



• A business case document, which includes the business context, success criteria and a finan-cial forecast

• A first draft of the risk list

• A coarse grained project plan, showing phases and iterations

• A first draft of the software architecture document with a description of a candidate architec-ture

• A first version of the development case document

2.3.2 Elaboration Phase

The purpose of the elaboration phase is to analyze the problem domain, establish an architectural foundation, develop the project plan, and eliminate the project's highest-risk elements. The primary objectives of the elaboration phase are:

• Defining, validating and baselining the software architecture as rapidly as practical

• Baselining the vision

• Baselining a high-fidelity plan for the construction phase

• Demonstrating that the baseline architecture will support this vision for reasonable cost in a reasonable time

The most important deliverables of the elaboration phase are:

• A use-case model which is approximately 80% complete

• Supplementary requirements capturing the non functional requirements and any requirements that are not associated with a specific use case

• An executable architecture, i.e. a first version of the system with minimal functionality, but ac-tually built with the intended architecture

• An updated software architecture document

• A revised business case document

• A revised risk list

• A development plan for the overall project, including the coarse-grained project plan, showing iterations and evaluation criteria for each iteration

Note that only at the end of the elaboration phase effort and cost can be estimated with reasonable accuracy (+/- 20%). All estimates before the LCA milestone are rough "guestimates" with a high degree of uncertainty and must be treated as such.

2.3.3 Construction Phase

During the construction phase, all remaining components and application features are developed and integrated into the product, and all features are thoroughly tested. Typically in this phase a number of iterations (3 to 6) are required to completely implement the system. The primary objec-tives of the construction phase are:

• Building the system in a series of preplanned iterations

• Achieving useful versions (alpha, beta, and other test releases) as rapidly and as practical

The outcome of the construction phase is a “beta” release of the product ready to put in hands of its end-users. At minimum, it consists of:

• The software product, integrated on the target platform

• A user manual



• Release notes

Typically, at the end of the construction phase 95% of the required functionality is implemented and the system is stable enough to be used by selected users in a production environment.

2.3.4 Transition Phase

The purpose of the transition phase is to transition the software product into the user community. Typically this requires a number of “release candidates”. A release candidate is a software release which has been thoroughly tested and found to be ready for productive use by the development team. It is then given to end-users. If no more serious bugs are detected by end-users within a predefined timeframe, the release candidate is declared to be the final release and the PR (product release) milestone is reached.

At the end of the transition phase, one generation of a product or system is completely developed and deployed. Future enhancements to the system are typically done in the context of a new pro-ject, i.e. another succession of the four phases inception, elaboration and transition, which result in a new generation of the system.

2.4 Disciplines

While phases and iterations describe the organisation of a project along the time axis, disciplines describe what needs to be done, how it should be done, and by whom. Each discipline describes a set of artefacts (work products) and the activities that lead to them. The nine disciplines of RUP are:

• Business Modeling The purpose of this discipline is to understand the organisation and dy-namics of the business into which the resulting software system will be deployed. The main artefacts of business modelling are a business use case model (description of business proc-esses) and a business object model (description of the structure of a business). Note that this discipline is optional, not all projects need business modelling.

• Requirements This discipline covers all activities needed to elicit, understand, and document the requirements for the software system to be built. The most important artefacts are a vision document which includes a list of product features and a use case model.

• Analysis and Design The purpose of this discipline is to create the architecture and the software design of the system. The most important artefacts are the design model (an object model of the system) and the software architecture document which describes the high level architecture of the system.

• Implementation This discipline covers all implementation activities, i.e. writing source code, unit testing, and building the system. The most important artefact is the implementation model, which is made up of all source code files, build scripts and resulting executable files of the project.

• Test This discipline contains all activities needed to test a product, with the exception of unit tests, which are covered by the Implementation discipline. The most important artefacts are a test plan, test cases, test scripts, and a list of known bugs.

• Deployment The purpose of this discipline is to create all materials which are delivered to the operators and / or end-users of the software product. The most important artefacts are the in-stallation medium (CD-ROM, tape, tar file, etc.), installation scripts, installation notes, and end-user documentation.



• Configuration and Change Management This discipline covers two related areas of work in every software project. First, all activities for configuration, version and release management, i.e. identifying the components that are part of the project, the hierarchical organisation of these components, and versioning of all project artefacts and software releases. Second, all activities for change request management, i.e. maintaining a list of change requests and evaluating these change requests. The most important artefacts of this discipline are a con-figuration and change management plan and a list of change requests.

• Project Management The purpose of this discipline is to plan and monitor the project. The most important artefacts are a high level software development plan, a detailed plan for each iteration (produced shortly before the iteration begins), iteration assessment documents for each completed iteration (produced shortly after the end of an iteration), and a risk list.

• Environment This discipline contains all activities needed to configure the development process for a particular project and to set up the development environment. The most impor-tant artefacts are a development case, programming guidelines and if needed user interface guidelines. The development case is a document which essentially describes what artefacts of RUP and otherwise are used in a particular project.

3. Applying RUP for Contract Development Work

This chapter describes how we apply RUP for contractual software development work. We found that the iterative nature of RUP lends it very well to contractual work for several reasons. Most im-portantly, customers get executable releases very early in a project. This allows early feedback and also builds confidence in the capabilities of the contractor. Compared to traditional waterfall projects, more effort needs to be expended on project management and also more customer in-volvement is needed. However, this is more than offset by a much higher probability that the pro-ject will succeed.

3.1 Assumptions and Policies

We do not claim to be wizards who can build every conceivable software system. We will take on a project only if we are positive that we have the know-how and experience needed to be successful. We consider it unprofessional and unethical to embark on a project where this is not true2.

That said, here is an open ended list of assumptions and policies we based our approach to con-tractual software development on:

• Requirements change frequently Some people think that requirements should be specified at the beginning of a project and then be "frozen" until everything is implemented. We have never seen this to work in practice. Requirements change for several reasons3 and a real world development process must allow for this instead of negating or even fighting changing requirements.

2 We have seen situations where a contractor starts a project in full knowledge that the project is doomed because the ex-

pectations of the customer are completely unrealistic, or the contractor does not have the necessary knowhow, or some other reason. The idea is to get (just) to the point where the accumulated costs are so high that abandoning the project is unlikely and then hope that the customer will continue to fund the project, despite all delays and other problems. This is not our style, we firmly believe in long term and positive relationships with our customers.

3 Some reasons are: building a system leads to a better understanding of the problem at hand; market changes; legal changes; mergers of companies; technological changes.



• Small and powerful teams We believe that interesting software systems can and should be built by small and powerful teams with 3 to 10 developers in 18 months or less. We know that 5 highly skilled and motivated developers working according to a realistic project plan can get done much more than a crowd of 20 mediocre developers working in chaos and under insane schedules. We acknowledge that some systems are so big that they can not be built by 10 first class developers in reasonable time. In this case the first choice should be to break the large system down into a number of more manageable systems and build each one with a small and powerful team.

• Customer is heavily involved All successful projects are characterised by tight integration of the customer in requirements management and some other critical areas. The "here are the specs, go build the system and don't bother me" style of customer/contractor relationship doesn't work in our experience.

• Incremental delivery We deliver an executable release of the software at the end of every it-eration, with the possible exception of the very first iteration of the inception phase. Each re-lease is accompanied by release notes, installation instructions, and all other support material needed to successfully install the software. In order to fully realize the benefits of iterative de-velopment, we need timely feedback from the customer to each release.

• Open internals policy Some of the artefacts we produce are of contractual nature (eg. most requirements artefacts), and some are purely internal (e.g. configuration management plans, test cases, design models, and so on). While "official" artefacts are part of our delivery to the customer, it is our policy that customers have access to all internal artefacts of their project at all times too.

• Reuse of source code and other artefacts We will use source code which we already have in new projects free of charge, thus decreasing development time and cost for the customer. In return we expect that the customer agrees that we can reuse all new source code created in their project, of course with the exception of source code containing business secrets of the customer. Legally, the customer gets the right to do whatever he pleases with the source code (i.e. use it, modify it, sell it, etc.), and we get the same right minus the portions of the source code which are business sensitive. This policy applies to all artefacts, not just source code4.

• Productivity follows quality We do not believe that quick and dirty solutions save time in the long run. It is our experience that changes to systems built "quick and dirty" are much more time consuming than to well designed systems. Productivity in the long term depends on the effort to be expended on changing, enhancing and porting a system. So, in the long run, high productivity can only be achieved through high quality systems.

• Full delivery of all artefacts At the end of the project, the customer gets a copy of the con-figuration management repository of the project. This includes all artefacts ever produced for the project, complete with version and release histories. Many customers take over further de-velopment of the system after we handed over the repository.

Many of these assumptions and policies exist in order to create as quickly as possible a positive relationship with the customer in general and to build trust in particular. The best way to create trust is to show competence and dedication; the best way to show competence(myabe:both of these qualities) is to deliver results early.

We firmly believe that a project can only succeed if we have a positive relationship with the cus-tomer. If the relationship turns adverse for some reasons, then the project is very likely to fail. The best way we know of to avoid this is — in addition to working professionally — is to be completely open about the status of the project at all times.

4 Please note that we do not work for competitors of our customers in similar projects without explicit agreement of the

original customer. Therefore, even generic source code and other generic artefacts will not be reused in projects for com-petitors without the customers agreement.



3.2 Project Scope

Given the four phases of RUP — inception, elaboration, construction and transition — what phases should be contracted out? We do have strong preferences, but before stating them, a few defini-tions are in order.

3.2.1 Project Types

Here are some important terms, which are unfortunately confused quite often:

• Product A product is a software system such as a word processor, a control system for a power plant, an airline reservation system, a GUI framework, or the software in the fuel injec-tion system of an automobile. Successful software products tend to live quite a long time5 and are enhanced many times during their lifetime.

• Project A project is an organised effort to either create a new software product or to substan-tially modify an existing software product. Typically, every major release of a product is built in the context of a project. In this scenario the first project creates the software either from scratch or by using parts from other products6 and results in a 1.0 release of the product. All subsequent releases are modifications to an existing product and built in the context of a pro-ject in its own right.

• Process A process is the set of rules, guidelines, recommendations and principles used to organise, plan and monitor a project. RUP is but one example for a process and there are many others.

Given these definitions, a project is either new development work or (substantial) modification of an existing product. This is true for contract development work, too. Table 2 below lists all types of projects we are offering to our customers.

Project Type Remarks

New development This is by far the most frequent type of project we do.

Modification of an existing product, which we de-veloped initially

This is quite frequent, too. Many customer take over the evolution of their product after release 1.0 themselves, though.

Modification of an existing product developed by somebody else

This is rather rare. We did and still do such projects. Most of these projects are reengineering and software stabilisation projects where the initial developers are no longer available.

Table 2 — Project Types

3.2.2 Begin and End of Contractual Work

At what points in time in a project should a contractor start and end his involvement? Our prefer-ence is to start early in inception and carry on till end of transition. This applies equally for new de-velopment work and for modifications to an existing product.

The earlier we are involved, the better we can understand the customers real needs and the better we can guide requirements collection and documentation. If we start early in inception, we can make sure that the relevant RUP artefacts (Vision Document, Use Cases) are created in the proper level of detail and quality to be useful in the elaboration phase. Sometimes we are pre-

5 Successful software seems to almost always live longer than it's creators initially thought. The best example for this was

the Y2K problem. 6 Most often it is a combination of building some parts from scratch and reusing some parts scavenged from existing prod-

ucts.



sented with a written specification prepared by the customer and asked to come up with a plan and/or quote for "implementing what's in the specs". While we positively do appreciate an initial specification from our customers, such a specification is not substitute for a well done inception phase. The only exception would be a customer who is fairly experienced with RUP and thus de-livers all relevant artefacts for the LCO (lifecycle objectives) milestone.

We prefer to carry on till end of transition, because this is what most customers want and also be-cause this way we are faced with the consequences of architectural decisions we made in the elaboration phase, which is the only way to improve ourselves. We have done some projects where the contract ended at the LCA (lifecycle architecture) milestone, because the customer wanted us just to define and verify the architecture and then take over the project themself. How-ever, in this case coaching of the customers’ team for at least some time during the construction phase is essential.

3.3 Customer Involvement

Even though the actual development work is contracted out by the customer, there needs to be strong involvement from the customer. This is pretty obvious for requirements work, but not so ob-vious for other areas such as testing, project management, and configuration management.

The table below shows a distribution of responsibilities between us and the customer, which we found very workable in practice.

Discipline Customer Involve-ment

Responsibilities of Zühlke Responsibilities of Cus-tomer

Business Modelling See comments below

Requirements mandatory Create and maintain all re-quirements artefacts

(1) Provide input for require-ments artefacts, (2) Review and approve requirements artefacts

Analysis & Design optional Create and maintain all analy-sis & design artefacts

May review critical artefacts

Implementation optional Do all implementation work May do some code reviews

Test mandatory Write and execute test cases for unit, integration, and sys-tem testing

(1) Acceptance testing, (2) Provide feedback for every development release delivered to customer

Deployment optional Prepare packaged releases of the software, complete with release notes and installation programs

Most customers install re-leases on the target and/or test systems and write end user documentation. However, if wanted, we can handle this too.

Configuration & Change Management

mandatory Set up and run a configuration management system, maintain change request list, evaluate change requests

Issue change requests

Project Management mandatory Plan and monitor project, cre-ate and maintain all PM arte-facts

Assign priorities to features, use cases, change requests and bugfixes

Environment optional Set up development environ-ment and development case

May review development case



Table 3 — Responsibility Matrix

We found that customer involvement is critical in the requirements, testing, configuration & change management and project management disciplines.

3.3.1 Business Modelling

The business modelling workflow is highly dependent on the type and scope of the project. Small technical projects almost never need business modelling, medium to large commercial projects almost always need some business modelling. When needed, we strongly recommend to do busi-ness modelling as a separate (small) project before embarking on a software development project, especially if the development work is contracted out. Otherwise too much time will be lost in the requirements workflow.

3.3.2 Requirements

The purpose of the Requirements workflow is to elicit, organise and document the requirements for a software product. Most customers already have some sort of requirements documents when they start looking for contractors who can develop the software. The size and quality of the require-ments documentation varies widely from a few pages with a brief and concise mission statement to several thick binders with tons of detailed specifications. We actually prefer a concise mission statement over voluminous detailed specifications (a.k.a. "Victorian novels"), because the latter are almost always a sign of a waterfall process with a lengthy and purely paper-based specification phase up front.

Regardless of the size and quality of the requirements documentation we receive, we always need the critical requirements artefacts according to RUP (vision document, use case model, require-ments attributes). We will create and maintain these artefacts, but we need the customer to (a) provide input to requirements, (b) decide what is a requirement and what isn't and (c) review and approve the requirements artefacts. This means that the customer needs to dedicate at least one person to the project who is knowledgeable and experienced in the application domain, has the au-thority to make decisions, and has time to work for the project (i.e. review requirements, attend meetings, be available for questions, etc.).

3.3.3 Testing

We do all the routine testing for every release delivered to the customer. However, it is essential that a customer installs and exercises every release we deliver, and provides us with feedback in the form of change requests and bug reports. Another duty of the customer is to perform the final acceptance test. We need to get all test cases from the customer prior to the formal acceptance test, so that we can pre-test the product in order to minimise the time needed for the acceptance test. Although we do not consider it the contractors (i.e. our) responsibility to write test cases for acceptance testing, we can help writing them if a customer has not enough resources or experi-ence to do this.

3.3.4 Configuration & Change Management

There is no direct customer involvement in this discipline, i.e. we handle all CM work. However, we are using change requests to keep track of requirements changes and we need customers to agree to this mechanism. We do the administrative work, i.e. we are maintaining the list of change requests with all relevant attributes (description of requested changes, priority, status, etc.). Cus-tomers can send us change requests in writing (the preferred way for complex changes) or just tell us what they want differently and we write it up (preferred for simple changes).

We start using change requests after the LCA milestone, i.e. at the end of the elaboration phase. During inception and elaboration change requests are not needed, because this is the time when the system is defined and all (or almost all) options are still open.



3.3.5 Project Management

At first glance, customer involvement in project management seems to be illogical. Of course we do all planning work and day-to-day management. Customers are involved in project management in two circumstances, however:

• Towards the end of elaboration we draw up a project plan for construction and transition. The important parts of this plan are number of iterations, start and end of iterations, objectives for each iteration, and planned functionality for each iteration. This plan is reviewed by the cus-tomer. The priorities of features and use cases are a very important customer input. To con-tinue the project, we need a project plan both the customer and we agree upon.

• Before the start of each iteration, we create an iteration plan. What goes into an iteration is roughly sketched out in the project plan, but reality might have changed since the last update to the project plan. So, before each iteration we review with the customer which functionality should be built in the upcoming iteration, which change requests should be implemented, and which bugs should be fixed.

We prefer iterations with a length of approximately one month. Shorter iterations tend to generate too much planning overhead. Longer iterations increase risk because the period of time between releases and thus customer feedback becomes too long.

While an iteration is under way, we do not change the plan for the iteration, unless we see that the objectives of the iteration cannot be achieved. In this case we cut down on the functionality, change requests or bugfixes sscheduled, finish the iteration on time (but with less results than planned), and re-plan. Extending an iteration by more than a few days increases risk, so we try to avoid this.

3.4 Typical Artefacts

There are 60+ artefacts mentioned in RUP, but we have never needed all of them in a single pro-ject. Our policy is to keep the artefacts to the bare minimum needed, because every single artefact needs to be maintained and thus creates work. The rest of this chapter explains which artefacts we typically use in projects of medium size (3 to 10 developers).

3.4.1 Requirements

The following table summarises requirements artefacts we use in our projects. Artefacts with a status of "mandatory" are used in every single project, others are used as needed.

Artefact Status Formats and Tools

Vision Document Mandatory Document, 10-25 pages

Use Case Model Mandatory Document, 1-3 pages per use case

Stakeholder Requests If needed Document, 5-20 pages

Supplementary Specifications If needed One or more documents

Use Case Storyboard If needed Sketches on a piece of paper for simple systems, so-phisticated GUI prototype for complex systems

Glossary If needed Document, 3 to 20 pages

Table 4 — Requirements Artefacts



The Vision document captures requirements at the highest level. High-level requirements are called "features". The list of features in the Vision document defines the scope of the system. The vision document is one of the most important artefacts in every project.

The Use Case Model describes the functional requirements on a system as a collection of use cases and actors. A use case is a typical way of using a system, i.e. handling a claim in an insur-ance system or opening an account in a banking system. Most of the products we build have be-tween 10 and 40 use cases.

The Stakeholder Requests document can be regarded as a "wish list" that will be used as pri-mary input to define the high level features of a system, as described in the Vision document. Note that there is an important distinction between a "request" and a "requirement". A request is basi-cally something a stakeholder (customer) would like to have, whereas a requirement is something that has been decided and shall be built. Not all requests become requirements. We use this arte-fact if there is an abundance of ideas for requirements in a project, but the available resources do not allow to build everything requested.

Supplementary Specifications contain all requirements, which can not be expressed in the Use Case Model. Normally these are non-functional requirements, such as design constraints, reliabil-ity, scalability, and so on. Depending on the number of non-functional requirements, there may be more than one document with supplementary specifications. If there are only very few and quite simple non-functional requirements, they can be written down in the Vision document.

A Use Case Storyboard describes how a use case is presented by the user interface of a system. Note that the description of use cases themselves should be as independent from a specific user interface as possible, hence the need for use case storyboards. We use storyboards if the user in-terface is complex and critical for the success of the project.

We use a Glossary if a project has a lot of project specific terminology and/or requirements are numerous and hard to nail down. Much of the value of having a glossary comes from the fact that writing down and explaining a term forces one to investigate the real meaning of a term.

3.4.2 Analysis and Design


Software Architecture Document Mandatory Document, 10-25 pages

Design Model Mandatory Kept in the repository of a CASE tool, such as Rational Rose or Together Control Centre

Data Model If Needed ER model. Exists either as a document or in a special-ised tool such as ERwin or Rational Rose.

Table 5 — Analysis and Design Artefacts

The Software Architecture Document contains a brief overview of the high level design of the system. It describes the architecture in a number of views, including a design view, a process view, a deployment view, and an implementation view. It is one of the most important documents of every project. Together with the vision document, it provides a quick overview of the goals and adopted solutions of a project.

The Design Model is essentially an abstraction of the implementation of the system. It is an object model consisting of classes, methods, attributes, relationships, packages, and any number of dia-grams to visualise the object model. The design model lives in the tool used to create it, ie. there is not a separate design document.

The Data Model is needed only if the project uses a relational database. It is a classical entity-relationship model. Depending on the size of the data model, it is either simply described in a document or it is created with a specialised tool.



3.4.3 Implementation


Implementation Model Mandatory Source code, build scripts, and supporting files

Table 6 — Implementation Artefacts

The Implementation Model is simply the collection of all material required to build the system, i.e. source files, header files, build scripts such as makfiles or ant files, object files, executable files, and so on.

3.4.4 Test


Test Plan Mandatory Document, 5 to 15 pages

Test cases Mandatory Documents, tools specific scripts, or hardcoded in source code

Test Report Mandatory Document, 2 to 10 pages, or integrated into iteration assessment document

Table 7 — Test Artefacts

The Test Plan is a brief document describing the strategy for testing, i.e. what kind of tests are performed and why, what tools are used, and what the test cycle completion criteria are.

A Test Case describes an individual test to be performed, including input data and expected re-sults. Depending on the tools used, test cases are either documents (manual tests), scripts (to control a testing tool), or source code (for unit testing with JUnit or similar frameworks).

A Test Report is a document summarising the findings of a test cycle performed within an itera-tion. Depending on the size of the project, we either use a document of its own right (medium or large projects) or we describe test results as a section in the iteration assessment document (small projects).

3.4.5 Deployment


Installation Artifacts Mandatory CD-ROM, tar file, zip file

Release Notes Mandatory Document, 1 to 5 pages

End User Support Material Optional User Manuals, Training material, etc.

Table 8 — Deployment Artefacts

The term Installation Artefacts stands for all material needed to install the software on one or more machines. Typically this is either a CD-ROM or an archive file (tar or ZIP) which contains all required binaries, installation scripts, and configuration files.

Release Notes describe the peculiarities of a release, i.e. new features, known bugs, how to install it, and dependencies on other software.



The term End User Support Material stands for all material given to the end users of the system, as opposed to material intended for operators of the system. End user material includes user manuals, tutorials, reference manuals, and training material. Depending on the agreement with the customer we either provide end user material or we do not. Frequently our customers prefer to write end user manuals and training material by themselves.

3.4.6 Configuration and Change Management

Artifact Status Formats and Tools

Configuration Management Plan Mandatory Document, 5 to 15 pages

Change Request Mandatory Document or entry in a change request management system

Table 9 — Configuration and Change Management Artefacts

The Configuration Management Plan documents the strategy and policies for release control and version management. This document can be reused from one project to the next to a large degree.

A Change Request describes a modification requested by the customer against a defined base-line. For small projects, a simple list with all change requests and an indication of the status of each change request suffices. For medium or large projects, we use a change request and bug tracking system.

3.4.7 Project Management


Software Development Plan Mandatory Document, 5 to 15 pages

Risk List Mandatory Document, 2 to 10 pages

Iteration Plan Mandatory Document, 2 to 10 pages, or project planning tool

Iteration Assessment Mandatory Document, 2 to 10 pages

Table 10 — Project Management Artefacts

The Software Development Plan contains among other things a rough project plan listing all iterations with planned start- and end-dates, as well as objectives for each iterations. It includes other planning and management artefacts by reference.

The Risk List contains a description of the top 5 to 15 risks of the project. For each risk, counter-measures to reduce the likelihood of materialisation of that risks are described as well as a contin-gency plan in case the risk does materialise.

An Iteration Plan is a detailed plan for a single iteration. It is prepared shortly before the start of the iteration. At a minimum, it contains a list of the features, change requests and bug fixes to be implemented in an iteration, including estimates and responsibilities for each work item.

An Iteration Assessment documents the outcome of a completed iteration. It's purpose is to close the feedback loop, i.e. to learn from experiences made in an iteration. Typically an iteration as-sessment meeting is held after the completion of each iteration and the findings are documented. The customer is encouraged to participate in these meetings to learn first hand what went well and what did not in an iteration.



3.4.8 Environment


Development Case Mandatory Document, 2 to 10 pages

Programming Guidelines Mandatory Document, 10 to 30 pages

User Interface Guidelines Optional Document, 3 to 30 pages

Table 11 — Environment Artefacts

The Development Case documents how RUP is applied in a particular project. At a minimum, it contains a list of all artefacts used by the project.

Programming Guidelines set standards for coding style. We have company-wide guidelines for C++ and Java which are used unmodified by most projects.

User Interface Guidelines are used if a project delivers a substantial user interface. Where avail-able, we use standard user interface guidelines for the platform we are developing for, e.g. Suns Java GUI guidelines or Windows GUI guidelines from Microsoft. Where no standard guidelines ex-ist (ie. for embedded systems with a user interface), we assign one of our usability experts to de-sign product specific guidelines.

4. Forms of Contracts

From the point of view of contracts, a development project typically is broken down into 3 con-tracts: one for the Inception phase, one for the Elaboration phase and one for the Construction and Transition phases. For small projects, the contracts for Inception and Elaboration are often com-bined into a single contract.

A sequence of contracts rather than a single contract for the entire project reduces the develop-ment and financial risk both for the customer and for us. This is also in line with the increase of knowledge of the requirements and the technical solution as the project unfolds. The rest of this chapter describes the main characteristics of the individual contracts.

4.1 Inception Phase Contract

Typically this phase (and thus contract) lasts between 2 weeks for a very small project and 4 months for a large project. Most often this contract is for time and material, with a budget limit set by the customer. The most important deliveries are:

• A proof of concept software prototype for medium and large projects (none for small projects)

• A vision document, with a brief description of product features

• An outline of the use case model

• A first draft of the software architecture document, describing one or more candidate architec-tures for the system

• A first draft of the risk list

• A detailed estimation and plan for the Elaboration phase

• A rough estimate and plan for the Construction and Transition phases

The estimate provided at the end of the Inception phase for the overall project is in form of a range of effort and cost. We provide a best case estimate and worst case estimate, based on comparison with similar projects done in the past. For this kind of estimate we utilise a commercial estimation



tool called "KnowledgePlan". This tool uses a database with data on 5000 completed projects for estimates.

At this point of time the range is still quite substantial, typically +/- 40% (e.g. best case effort 600 days, worst case effort 1400 days). Depending on the outcome of the inception phase, the cus-tomer decides to continue or to abort the project. There is nothing wrong with a decision to abort a project at this point in time. One of the acceptable results of the Inception phase can be the reali-sation that the project is not feasible or too risky and thus better avoided.

4.2 Elaboration Phase Contract

Depending on the size of the project, this contract lasts between 1 and 6 months. Typically it is for time and materials with a budget limit set by the customer. The most important deliveries are:

• A working software system, demonstrating the feasibility of the architecture by implementing a subset of the features of the product. The code base of this system is also the code base of the real product, in other words, it is not a "throw-away" prototype.

• A detailed use case model

• A detailed software architecture document

• A refined estimate and plan for the Construction and Transition phases

During this phase we deliver a number of software releases to the customer, typically one at the end of each calendar month. Each release adds functionality to the previous one. The customer gets intermediate results of all artefacts with each release, i.e. source code, plans, documents, models, etc.

The estimate provided at the end of the Elaboration phase is also in form of a range (best / worst case), with a precision of typically +/- 20%.

Like before, the customer decides at the end of Elaboration if he wants to continue the project. At this point it is still acceptable to decide not to carry on with the project. One reason might be that it turned out the effort to realise the system would be too large, or that the architecture for the system would be too complex and thus too risky. Once the decision is made to go ahead with the project and enter the Construction phase, there are no more planned project continuation reviews, i.e. the project is normally carried through till the end. In other words, after passing the LCA (Life Cycle Ar-chitecture) milestone at the end of the Elaboration phase, there should no longer be any technical or budget related reasons to abort the project. If it is still aborted, this must be considered as a fail-ure.

4.3 Construction and Transition Phase Contract

This contract lasts normally between 6 weeks for a small project and up to 12 months for a large project. We recommend this contract to be for time and materials, with a budget limit set by the customer. If the customer wishes so, we can offer a fixed price for these phases if the following is true:

• The requirements are very stable and very well understood

• There are no significant dependencies on material or information to be provided by the cus-tomer

However, in our experience these two assumptions are almost never true. Therefore a time and materials based approach with a budget limit and tight integration of the customer into project con-trol delivers the best results.

A proven technique to limit risk for the customer and for us is what we call "feature based commit-ment". In this model, the list of features is prioritised by the customer into three priority levels:



• Priority 1 features: these must be implemented, otherwise the product is useless

• Priority 2 features: these are highly desirable, but the product is still useful if some of them are missing

• Priority 3 features: these are nice to have

A typical contract with a customer is based on this list. Under such a contract, we commit to im-plement all priority 1 features, a certain percentage of priority 2 features (70% typically), and an-other percentage of priority 3 features (30% typically) within a given budget.

The mode of work is the same as in the Elaboration phase, i.e. monthly deliveries of software re-leases and participation of the customer in all iteration planning and assessment meetings. At the end of the project, the customer gets all artefacts produced by the project, including a full copy of the project repository.

4.4 Maintenance Contracts

Many of our customers prefer to take over continued development and maintenance of the soft-ware we developed initially. For those who do not, we are offering the following options:

• Continued development is handled like a new project, i.e. we are offering our services for de-veloping a new version of the product. The new version is created with the same process, i.e. there is an Inception, Elaboration, Construction and Transition phase. We recommend this ap-proach if a customer needs a major upgrade of a product every now and then, but nothing in between.

• Continued development is handled as an ongoing effort. We recommend this approach if there is a need for permanent changes and enhancement of a product. A proven approach for this kind of maintenance is to permanently assign a team of at least 3 software engineers. In order to avoid that the assigned staff gets bored and subsequently performace starts to suffer, every year one of the 3 engineers is replaced. This way knowhow is preserved in the maintenance team and the assigned engineers still have a chance to be involved in a new project after 3 years, which keeps their motivation.

• A service contract tailored to the customers needs. Typically a service contract covers critical bug fixes after expiration of the warranty period. We recommend this approach if no functional enhancements are needed, but there is a need for help with operating the software and trouble-shooting problems.

Service contracts are priced depending on the resources needed to fulfil the contract. Typically they are fixed price for a given period of time.

5. Supporting Infrastructure and Technical Expertise

5.1 Software Engineering Process Group

To provide process related support for development projects, we maintain a software engineering process group (SEPG). This group consists of 5 active software engineers who devote part of their time to the permanent improvement of our software development practices. The SEPG maintains a knowledge base accessible to all developers with process documentation, templates for artefacts, examples of artefacts, programming and design guidelines, process customisation guidelines, pro-ject post mortem reports, tool information, and more. Members of the SEPG also provide coaching and support for development projects if needed.

The software engineering knowledge base is maintained as a website in our corporate intranet. The screen shot below shows the entry page of this website.



Figure 2 — Software Engineering Knowledge Base Homepage

5.2 Development Tools

To make a development process effective, professional tools are required. Here is an overview of our development infrastructure and a non-exclusive list of tools we are using at the time of this writ-ing (January 2003):

• PC based developer workstations running Windows or Linux

• Development servers running Windows, Linux and Sun Solaris

• CASE tools: Rational Rose, Rational XDE, Rational Rose Realtime, Together Control Center



• Configuration management: Perforce, CVS, Microsoft Source Safe

• Development environments: Microsoft Visual Studio .Net, Eclipse

• Application servers: BEA Weblogic, IBM Websphere, Microsoft .Net Servers

• Testing and bug tracking tools: JUnit, Bugzilla, Testrunner, Test-Director, Clear Quest

• Project planning tools: MS-Project, KnowledgePlan for estimates

• Software metrics tools: RSM, Krakatau

This list of tools is constantly refined and adapted if needed.

5.3 Software Development Staff

The most important success factor in a software development project is not the set of tools used, though. It is the people working on the project, their skill set, experience, dedication and social competence. This is why we apply very high standards for hiring and training employees. Before hiring, every candidate is examined in detail for his or her previous accomplishments, experience, technical skills, and social skills. All of our employees in software development have formal educa-tion in software engineering or computer science. Most have certifications in their area of expertise, such a Microsoft Certified System Developer, Sun Certified Java Developer, or BEA Certified De-veloper. The core skill set of every software developer includes the following topics:

• A working knowledge of our software development process

• Requirements engineering with features and use cases

• Object modelling and UML

• Object oriented programming with C++, Java, C#, or Smalltalk

• One or more of the operating systems Windows (2000, XP, CE), Linux, Unix, and Realtime-Systems such as VxWorks, JBed or Linux-RT

On top of these core skills, employees specialise in particular areas. Examples for areas of spe-cialisation are database systems (both relational and object oriented), real-time embedded sys-tems, software architectures, distributed systems, security technologies and usability engineering. To sustain a high level of competence, developers receive 20 days of training each year.

6. Conclusions

Developing substantial software systems is inherently a task with many risks. There is no "silver bullet [5] which guarantees success under any circumstances. We found that in order to success-fully deal with these risks, the following must be given:

• A team of skilled, experienced and dedicated software developers

• A fine tuned agile development process, based on incremental deliveries

• Appropriate tools such as CASE tools, development environments, and configuration man-agement and version control systems

• An open and transparent relationship with the customer

• Direct involvement of the customer in requirements specification, iteration planning and as-sessment, and testing

• Fast feedback from the customer to every intermediate release delivered



We have refined our ability to deliver quality software within agreed schedules and budget over many years. To this date (January 2003), we have successfully completed over 20 projects with the process outlined in this paper. References are available upon request.

Appendix 8 contains a list of questions which may help you to evaluate a software contractor.

7. Appendix: References

[1] RUP Online Documentation A commercial product from Rational Software. See www.rational.com

[2] The Rational Unified Process — An Introduction Book by Philippe Kruchten, Addison Wesley, 2000

[3] Software Project Management — A Unified Framework Book by Walker Royce, Addison Wesley, 1998

[4] Managing Software Requirements Book by Dean Leffingwell and Don Widrig, Addison Wesley, 2000

[5] No Silver Bullet Article by Fred Brooks, published in IEEE Computer, April 1987

[6] Anchoring the Software Process Article by Barry Boehm, published in IEEE Software, July 1996

8. Appendix: Questions to Ask your Software Contractor

Here are some questions you might want to ask a potential software contractor:

• What development process are they using ?

• Ask for a copy of the documentation of the process

• Ask for sample artefacts, such as project plans, requirements documents, software architec-ture documents, source code

• Since when are they using this process ?

• How many projects have they successfully completed with this process ?

• Ask for references to contact

• How frequently are they delivering development releases ?

• What toolset are they employing ?

• What kind of education and certification have their developers ?

• How much and what kind of training did their developers receive in the past 3 years ?

• How do they check the qualification of new hires ?



9. Appendix: Contact Information

Website: www.zuehlke.com

Email: [email protected]

Switzerland: Zühlke Engineering AG Wiesenstrasse 10a CH-8952 Schlieren Phone: +41 1 733 66 11

Zühlke Engineering AG Gewerbestrasse 18 CH-4123 Allschwil Phone: +41 61 487 81 11

Germany: Zühlke Engineering GmbH Düsseldorfer Strasse 40a D-65760 Eschborn (Frankfurt) Phone: +49 6196 777 540

United Kingdom: Zuhlke Engineering Ltd 49 Great Cumberland Place London W1H 7TH United Kingdom Phone: +44 20 7724 6147

10. Appendix: History of Changes

Version Date Author(s) Comments

1.0 21-Jan-2003 M. Hirsch First published.

Technology

The Zühlke Software Development Process