Paul Geffen

Simple taxonomy of electronic media

2010-02-09T14:45:00.000-08:00

With three permissions we can characterize eight forms of communications.
It is assumed that the user can read all messages. The other permissions are:

user can write x--
world can read -x-
world can write --x

000 is a private read-only file
100 is a private writable file
010 is a public read-only file
110 is a write-once blog like Twitter
001 is email inbox where user can't edit messages
101 is email inbox where user can edit
011 is ???
111 is a Wiki

Google Buzz is like a Wiki.
672DVMTUSPHK
EAVB_IYHESFPAZC

Translation

2010-02-04T08:21:00.000-08:00

The work I did at IBM to lead and guide the process of development has taught me much that can be applied beyond the field of software. Every time I talk to another engineer I find that we talk about problems and processes in more or less the same language. When I talk to a writer or a teacher I find that when I explain my methodology in ways that are conventional for my field, that the terms and concepts still make sense in other fields although the language may be different.

SDLC Best Practices for Startups

2010-02-02T09:26:00.001-08:00

In my work as a development lead at IBM Rational I learned about the software development life cycle and the best practices as they were taught by Rational and used by our organization. This blog is an attempt to apply those concepts to the management of software development in a small company.

I recently approached a local startup with the idea. I proposed to teach them the principles of SDLC management. What I wanted to learn was how these ideas would affect their process and how this in turn would affect their growth. My theory is that the growth of a development group is inhibited from time to time by the way it is organized. Growth tends to level off (temporarily) as the group reorganizes to meet new challenges. What would happen if the structures and practices necessary for a large group were already in place before the group grew large? Would their growth curve be smoother? Would the group produce more in three years than a group that grew organically?
The way to find out is to do the experiment. The control groups are everywhere. What I want is a company that is willing to take on the overhead of more "process" as an investment toward a long term result.
I found this to be very difficult to sell.

I had more success with a friend who wants to start an e-learning web site. She is a teacher and has a curriculum that she believes has a market. Her challenge at this point is to enlist technical help from contract developers and make the best use of the contractors' abilities. What I did with her was to go over of the ideas captured elsewhere in this blog and teach her the terminology she needed to know to communicate effectively with her technical staff.
She found it easy to understand what I described but the idiom was somewhat new for her. What we were able to do was to translate her knowledge of what she wanted into language that a developer would understand. This made her interviews for new technical help much easier. Here's what she wrote:

"... just had a meeting with a potential technical contractor and I felt very confident in talking with him about what I need and how I’d want the process of working together to go – he actually congratulated and thanked me for knowing that they would like a document with my requirements mapped out on it and he was impressed that I understood that process."

Now I don't have any influence on how her contractors will do their work but I have been able to help start her off on solid footing as she learns how to manage a development effort.

Design for Test and Reliability

2010-01-31T11:10:00.000-08:00

Design for Test is part of standard practice in the microcontroller industry. It is discussed in the context of software engineering as well - but it is absolutely essential to the makers of large-scale microprocessors. The key concept is that the programming interface to a CPU does not allow access to many of the internals of the chip and additional logic is therefore added to the hardware to allow test and diagnosis of the device outside the scope of normal use. DFT is necessary to handle the fact that minor flaws can prevent execution of all diagnostic self-test operations.

Some years ago I had the opportunity to apply this principle to software architecture.
The application was a data abstraction layer in a multi-tier Windows application. The app used a relational database for persistence and presented the user with a set of objects. The layers in the design were as follows:

GUI
Business logic
Object model
Abstraction
ODBC
Database

The use of ODBC allowed a choice of databases with minimal configuration in the front end.
The part that I designed and built was the Abstraction layer and my goal was to make it as generic as possible. To accomplish this I put metadata in the database that defined the object model. The code in the Abstraction layer knew almost nothing about the business objects and their relationships to each other. It knew that there was such a thing as an object, that an object had properties, that objects could have relationships and dependencies, and what the property types could be. At first, all the other details were in data in the database that matched the expectations of the business logic. This allowed us to change the front end and the object model with little or no impact on the design or implementation of the Abstraction layer.

One way to apply the DFT principle to software is to add code that does some sort of internal self-test or consistency check. In this case, we didn't add any code that wasn't used in normal operation. In fact, we went in the other direction and stripped out any code we didn't absolutely need to get the Abstraction function to run. This led to an implementation that was very generic and concise. Even the definition of the generic data object was in the database.
Obviously some bootstrap code was needed to make this work. And in the revised and rewritten code in the second release we took out the initial bootstrap to improve performance.
The effect on test was simply that no unit test was needed for this part of the implementation. It either worked or it didn't. Like the FORTH language, which has a tiny interpreter, we started with a very compact core and built out from there.

Velocity and Scale

2010-01-24T06:42:00.000-08:00

These two concepts are central to my approach. If these concepts are understood and mastered, your great idea will have no limits. Here's how it works.

Velocity refers the speed at which a new idea can move from the real world (a designer or customer) through the development process and back out to the customer through a new version of your product. Your process needs to do two things:

optimize resources by managing the velocity of each idea, and
track the progress of each idea to measure velocity.

You cannot control what you do not measure, at least in science.

Scale refers to the way systems change as they grow. An example from biology is how organisms are built at different sizes. Exoskeletons don't work above a certain size: elephants have huge legs while spiders don't, etc. The rules of physics determine what is possible at every geometric scale. Surface to volume ratios constrain the shape of living things.

Your product is a living thing. It has a complex metabolism that will not scale well under the conditions of stress caused by your success and growth. You might be lucky, or very smart, but why not be systematic and consider the effects of scale on the velocity of the parts of your process?

This blog will continue to explore these ideas. The problems of scale will be the subject of a later article.

To measure velocity, we need to set up checkpoints and we need to mark the ideas so that we can track them through the process. If we rely on rough time-to-market measures and just look at the endpoints of the process, we miss the chance to find choke points along the way. We need a way to break the development process into manageable steps, and that is what the earlier posts in this blog have started to explore.

Once we can measure velocity we can also start to control it. It is not wise to move as fast as possible at all times. In the business world there is always pressure to produce results but there is also a trade-off between speed and quality. To improve quality we must be prepared to control the velocity of each step of the process.

The key to tracking ideas through the development process is to identify the artifacts that represent the ideas at each step. The artifacts are almost always documents of some kind. Only in the world outside can ideas be free-form. The type of artifact used to represent an idea will vary for each step and for each business context. For a very small development group, a single document may hold many ideas and a scrap of paper may contain a valuable idea. For a very large organization, a change management database is essential and provides great efficiency and flexibility at high cost.

Requirements

2009-12-21T19:34:00.000-08:00

Requirements artifacts are the documents that are created, managed, and published by business analysts or product management to define the scope and content of the development project.

Requirements must be captured and tracked in a version control system just like any other class of project artifact. In addition, specific requirements must be labeled in a way that allows items to be tracked through the entire life cycle: specifications, implementation, test, release, and support.

The granularity or specificity of the labels employed depends on the rigor of the project. A product with very high quality standards, such as a medical application, will have very detailed requirements that can be tracked in precise detail.

Requirements are often sketched out in natural language and carry informal instruction to the design specification team. A very effective way to organize functional requirements is to use the concepts of User Roles and Scenarios to develop Use cases. This process creates a formal model of the system. The model can then be analyzed to create formals specification of the components of the system.

An advantage of this approach is that formal requirements and specifications can be created as relatively small modules that can be worked on separately. This allows development and test of the modules or components of the system to proceed in parallel and supports the use of an Agile development process.

Customer to Requirements

2009-12-18T17:02:00.000-08:00

Customer reports are triaged into categories. Some will be treated as defects in the product.

Defect reports must be prioritized and fed back into the development cycle at the appropriate point. For example, critical defects can be sent directly to development for action while defects with low impact can be sent to design specification group for consideration.

Many customer requests are valuable inputs to the product management, analysis, and requirements gathering process.

All customer reports must be captured in a database, typically one that is optimized for the purpose, called a defect tracking system.

Customer to Implementation

2009-12-18T16:59:00.000-08:00

The users, clients, or customers have a direct link to the implementation when the product plans include a maintenance cycle.

Customer reports of problems go to triage, first in Support and later in Engineering. Reports that are approved by both support and engineering as Defects become work items for development and then part of the implementation. A mature process will include ways to expedite this flow.

Test Results to Customer

2009-12-18T16:18:00.000-08:00

Test results are usually not shared with customers in detail.

An important measurement of release readiness is test coverage and success rates.

The customer typically gets the results of test results in the form of an available release.

Implementation to Customer

2009-12-18T16:14:00.000-08:00

Implementation artifacts delivered to the customer must match the artifacts delivered to test.

It is possible for parts of the implementation to be withheld from the customer, so the released executable code is often a subset of the tested executable code.

The implementation may include internal support for test execution and performance profiling. These features may be turned off for the customer if they affect the behavior or performance of the product.

Another category of implementation artifacts that go directly to customers is screenshots included in documentation.

Implementation to Test

2009-12-18T16:09:00.000-08:00

Implementation artifacts - primarily executable code - are the primary channel of information from development to test execution.

Implementation status is another important part of the flow of information. For example, in a large project some parts of the implementation will be ready before others. If the implementation strategy provides a complete testable interface with incomplete logic behind the interface then the test efforts can be directed toward the most advanced parts of the implementation. The test results can to some extent be predicted.

Specifications to Customer Documentation

2009-12-18T16:07:00.001-08:00

Design Specifications are an important base of information for user or customer documentation.

Specifications to Test Plans

2009-12-17T16:53:00.000-08:00

Functional requirements and engineering specifications are the sources for the structure and content of test plans.

Specifications may include specific provision for tests. For example, instrumentation may be part of the implementation. Components may include functions that are designed to be tested independently of other components and outside of the overall system.

Specifications to Implementation

2009-12-17T16:48:00.001-08:00

Engineering specifications define the proposed implementation at an appropriate level of detail.

The intermediate artifacts between the design specification and the implementation are the project plan and task breakdown.

Specifications are often organized as a hierarchy, with general architectural plans as the more general type and implementation guidelines or standards as the more specific types.

Specifications will define the artifacts to build and the relationships between the implementation artifacts.

Specifications are written in a mix of natural and technical language.

Backlog

2009-12-17T16:43:00.000-08:00

Some of the artifacts in each class will represent approved, agreed-upon, active, or completed tasks.

Others will represent proposed tasks, work approved but not scheduled, etc. These artifacts comprise the backlog. A backlog is a natural and healthy part of the development process as long as it is managed correctly. One of the themes of this discussion will be to indicate when and how to address items in the backlog.

Here are some of the categories of the backlog.

Requirements that are published but not represented in specifications and/or test plans are in the design backlog.

Specifications that are not implemented are in the engineering backlog.

Implementation artifacts that have not been tested are in the test backlog.

Test plans and automation that have not been executed are also in the test backlog.

Test results that have not been reviewed are in the results backlog.

Customer reports that have not been triaged are in the support backlog.

Customer reports that have been triaged as defects but have not been fixed are in the engineering backlog.

Defects that have been fixed but where the fixes have not been delivered to customers are in the release backlog.

These are the most important components of the backlog.

Requirements to Customer Reports

2009-12-17T16:41:00.000-08:00

Customer reports can be evaluated or triaged by reference to requirements.

This allows customer reports and requests to be classified as defects, or as potential enhancements.

The reverse is also true. Requirements may refer to specific customer requests.

Requirements to Test Results

2009-12-17T16:36:00.000-08:00

Test results must correspond to requirements in terms of scope. That is, there must be a correspondence between features as described in requirements artifacts and successful test results. This mapping is driven by the coverage of features by test plans.

When required features are ranked by priority, test results can be used to evaluate release readiness. A release cannot be approved until all required, essential, or "release defining" features have been tested and these tests have passed.

Requirements to Test Plans

2009-12-17T16:30:00.000-08:00

Requirements artifacts help to define the initial scope of the test plan documents.

Requirements to Implementation

2009-12-16T18:43:00.001-08:00

Published project requirements can be compared to system features as described in functional specification artifacts.

An implementation must address the published requirements. All requirements must be represented by some part of the implementation.

An implementation may and often will include elements that are not described in detail by the requirements. While it is not necessary for the requirements to include all features of the implementation in detail, it is recommended that requirements be compared to the implementation to identify any extraneous functions.

Both product management (or business analysis) and engineering must sign off to confirm the congruence of requirements and specifications.

Requirements to Specifications

2009-12-16T18:35:00.000-08:00

Requirements artifacts, when published, form the basis for specifications.

Specifications must conform to requirements and may add features.

When requirements and specifications do not agree, negotiations between product management and engineering are required. The results of these negotiations may be captured in Change Request artifacts.

Ownership (or assignment) of responsibility for evaluating the state or quality of agreement between requirements and specifications belongs to both product management and engineering.

Project management responsibilities include the continual measurement of the level of this agreement. Periodic review of the published artifacts is necessary. Specifically, product management must review specifications and engineering must review requirements.

Initial Requirements

2009-12-16T18:33:00.001-08:00

The documents that define the initial requirements for a project have their basis outside the project. These documents are the major source of information from the natural world to the project.

Overview

2009-12-16T18:03:00.000-08:00

This document will define the scope of our discussion of SDLC.

We begin with the definition of the six primary classes of project artifacts.

1. Requirements
2. Specifications
3. Implementation
4. Test Plans and Automation
5. Test Results
6. Customer Reports

Requirements are documents that describe the initial or general goals of the software to be produced. These are written in a natural language (English in this case) by product management or a business process analyst. Requirements are typically based on intangibles like imagination and insight and form the primary reference documents for a project. These documents are used in turn by the engineering and documentation functions as the basis for more artifacts.

Specifications are engineering documents that describe architecture, design and development plans. These are written in a natural language by engineering management. They are based on requirements documents but include much more detail.

Implementation is produced by the engineering team from specifications and is typically in a language that can be interpreted and executed by a computer. Implementation artifacts are the tangible assets produced by the development process. Some of these assets are transferred from the development group to the customers in the form of a product or system.

Test Plans are produced by test engineering and serve as a framework for evaluation of the implementation. Test plans are based on both requirements and specifications, but not on the implementation.

Test Results are produced by test execution. Results are often in both natural language and machine-readable form.

Customer Reports are natural language documents created ad hoc as a result of the use of the implementation.

Backlog is orthogonal to the other six. It is a measure of the portion of the available artifacts (of any type) that has not yet been used to generate work or other results.

Many other useful terms will be defined in the discussion to follow. The six artifact classes stand out because they are well-understood and can be clearly defined. Most project documents belong in one of these classes.

Each of these artifact classes has a relationship to every other artifact class. Every one of these relationships will be explored at some point in the documents to follow.

Software Development Life Cycle

2009-12-11T08:27:00.000-08:00

This blog is written by an expert in the Rational ClearCase and ClearQuest configuration and change management toolset.