Getting Started with Shell Method

One of the analysts at a major customer of mine keeps commenting on the fact that he really likes the checklists, because he can just focus on the current checklist item and ignore everything else. He knows that when he hits a later step, it will probably utilize something he did previously, but he doesn’t have to remember what that future step will require.

This goes back to that cliff climbing analogy in a previous post. The climber just focuses on their current bubble of reality, and ignores the rest. Shell Method was designed to support this because no one can be expected to keep everything in their head just to work on a specific part of the process. So, the key to getting started is getting to the first checklist. To do that, you have to have your infrastructure set up to manage your projects.

Setting up the infrastructure
The infrastructure folder on the repository has all the details for this, but the process boils down to a set of decisions:

• Will you be using shellmethod.com as the process repository? This gives you a full, auditable process definition, background, overview, and guidance documents, review forms and integrated guidance, and full workflow definitions with zero effort, but you’re stuck with the style and format you see. If you’re going to roll your own; see you next year. That’s how long it will take.
• Which Configuration Management (CM) system will you use? Notice I didn’t say “if…” Download it or buy it, whatever. Get it in house and set it up. Your entire infrastructure (Web servers, file servers, local directories) will be impacted by this decision. Do it once, and spend the time necessary to learn the concepts and integrate the CM system into your file management infrastructure.
• Will you be using the BOTS example project site or tuning it to your preferred style and hosting it yourself? This is a pretty common approach, since the example site wasn’t set up to be a real showcase of Web design. If you’re using Dreamweaver, the Planning Stage has a Base Project Site all set up using a CSS template. Edit the template to suit your style and you’re done.
• Which HTML editor will you use? This drives how your sites will be set up and managed, and integrates with your CM tool. Once you have made a choice, integrate it with your CM tool (usually by cloaking cm directories in your sites).
• Which graphics generation tool(s) will you use? Face it: UML has won the process diagramming standards battle, so make sure your tools provide the right kind of integration. Auditors will be seeing a lot of UML diagrams from now on, so they’ll be more comfortable with UML than other styles. A comfortable auditor is much less of a bother.
• What will you use for project scheduling and reporting? Get it. Learn the basics.
• Do you have the full Acrobat? You’ll need it.
• Is your copy of MS Office up to date? You’ll need that too.

Executing your first project
OK. Now you’re ready to start up with Shell Method. The place to start is with the main documents. Read the PTTQ, the SDLC, the SCMP, and the SQAP. Read them again. Take notes.

The next step is the project planning templates. After they’re in and installed, start up a new project, in which the customer is a little firm known as Highland Office Supply, and you have been contracted to build the first release of their Basic Order Tracking System (BOTS).

Walk through each step in the planning stage checklist, and using the examples found on the BOTS example site, build all the intermediate products required by the checklist just as if you were doing it for a real client. Put the deliverables out on the project Web site. Do the presentations, the review forms, the project schedule, everything. If you have multiple team members, have different people play different roles. This will exercise nearly every part of your infrastructure (often to the breaking point), and point out the fact that you don’t have an identified Quality Assurance Reviewer. Now is the time to identify one. If you’re a solo practitioner, you’ll need to hook up with another solo practitioner and scratch each other’s backs.

Now do the same thing for the rest of the stages, working out the deliverables for the Core Features component and the Customer Management component of BOTS. Keep updating the site as you go.

This will take a while, but it’s a whole lot better than trying out the process for the first time on a real project. It’s embarrassing when you make a mistake and your friends point and laugh, but it doesn’t cost you money or hurt your reputation.

-Z-

Tin cans on a string

Well, it’s done. All the templates have been integrated, all the examples are posted, all the review forms have been updated, the final stage guidance has been posted, and review criteria and guidance have been synchronized with the latest SQAP. This has been one very interesting process.

Through this entire effort, the thing I noticed the most was the way that touching any one thing resulted in reverberations across a variety of linked items. This is a lot like a makeshift alarm made from tin cans on a string. Bother one tin can, and the cans on either side sound off as well. This is a lot like software development!

A formal process that can stand up to audit has a basic set of goals, requirements, and implementation specifics and it all has to link up properly or things get lost. In the case of Shell Method, the four main goals are:

1. Training & Qualification
2. Process Structure
3. Change Management
4. Quality Assurance
   

Training & Qualification

Who is responsible for doing what? How are they qualified? What training do they need? In other words, every action that someone takes in the Software Engineering (SE) process is associated with the fulfillment of a set of responsibilities related to their roles. Change a role (even the name) and everything in the process needs to be updated to reflect the change. Documenting the roles and responsibilities is the domain of the Project Team Training & Qualification Plan (PTTQ).

Process Structure

The steps we take in producing auditable software are clustered into stages, which in the SE world comprise a lifecycle. What are the goals of each stage? What are the inputs/outputs? Who does what? This is the domain of the SDLC, and it depends on the roles defined in the PTTQ.

Change Management

When something is changed, there needs to be an audit trail. This leads to version identification standards, the check-in/check-out and build process, and of course the process for tracking, evaluating, and approving changes to the software. The SCMP handles this, and it depends on the roles in the PTTQ and the stage deliverables in the SDLC.

Quality Assurance

Basically, documents have to get reviewed, and software has to be actually tested. There needs to be an audit trail that shows this was done, and done in accordance with the rules established for the project. There can be no ambiguity about who reviews what and how they do it. This drives the need for review criteria, guidance for the reviewers, and standardized forms to insure adequate coverage. The SQAP defines all this, and depends on the roles in the PTTQ, the deliverables in the SDLC, and the build and release processes in the SCMP.

Touching the heck out of the cans

The biggest problem I faced was the change in Shell Method from a single document stream (one set of documents for the entire application) to a component-based documentation stream. The advantage was all too clear because component-based documentation provides much the same advantages as component-based development, including smaller, more focused documents, easier access to expertise, and faster review cycles. This is basically applying Agile/eXtreme techniques to a formal, standard process. I already had the seedlings in place (PER-PDR pairing, iterative development, prototyping support, short durations between releases). I just needed to re-arrange the garden to support a different layout. Of course, seedlings already have roots…

The effect was similar to grabbing the string of cans and moving it to a bunch of new hanging points. Noisy. Very noisy.

As I modified each stage, I had to go back in and make changes to previous stages that I thought I had already finished. Now I know how a CPU feels when it’s executing a recursive loop. Anyway, after a final, four-day weekend of nearly constant pounding, I finished out the last template set and associated Web site artifacts, and none too soon.

The intent of Congress is absolutely clear: Information systems have to pass audit. But that’s another topic.

-Z-

Iterating your way to happiness

Wow, has it been more than a month since my last post? Time is surely zipping by for me these days. Got the planning and requirements stage sets out the door, but that's for another entry.

This one is about the difference between custom software development and packaged software development. Both Joel Spolsky and Eric Sink have recently written on the subject of upgrades and deciding what features go into what release. Eric and Joel are coming from the third-party software development world, and what they've written makes a lot of sense. Those of us that are satisfying customers one-on-one can take a lot of good points from these articles. Their overall theme appears to be: 1) Store up a bunch of issues, periodically decide what you're gonna do, then do it, 2) in between upgrades, don't promise anything, and 3) don't sell your product to inappropriate customers. I agree with all of this, but there’s more to the story for custom software developers.

Once upon a time, I was brought in to document a system that was almost ready to go into production. The developers were engaged in the typical endless loop of last-minute, absolutely critical (according to the requestors) change requests that were coming in the door via meetings, training sessions, email, phone calls, and I think I once saw a carrier pigeon. So, the first thing I did was get the sponsor to appoint a Primary End-user Representative (PER) that I had identified as a natural leader in a couple of meetings. Once she was in place and briefed on her role, I briefed the sponsor about their role as leader of the Change Control Board (CCB) and how the issue management process was going to go (standard Shell Method approach). The sponsor and PER were enthusiastic about this formality because this was one of those high-risk, high visibility, career-limiting, enterprise-wide applications. Meanwhile, the change requests continued to pour in.

The hardest part of bringing a currently uncontrolled project under control is finding a stopping point. When the developer is in the mode of responding to an endless flow of requests, a lot of other things (like testing, builds, and code promotion) don't happen, or don't happen properly. In this sense, a custom project should take the advice of Joel and Eric and "batch process" their changes, just like the packaged software providers do. In the case of custom software, one can't wait a long time between upgrades. As soon as one version is out the door, work begins on the next version. To keep the customer happy, one must be responsive. In order to be responsive, one has to address issues in a timely manner. This means short iterations, small versions, and rapid release cycles. The user community, sponsor, and developer should be constantly validating, analyzing, verifying, and assigning issues to various planned iterations while the developer works on executing the current (short!) iteration.

Fortunately, when one is brought in to document something, one can always throw up one's hands and exclaim "I can't document a moving target. Pick a set of features and lock the system. Push all other changes into future releases." At this point, you will usually be ignored. My solution to this is to stop work and wait for them to panic that the docs won't get done, which means they won't get a test plan or a deployment plan, which means nothing gets released. There are an awful lot of things you can be doing in the background while giving the appearance you've stopped work.

If you’re a developer in this situation, I recommend a similar approach. After all, your survival is at stake; your survival depends on your reputation, and failed projects are not good for the reputation. So stop responding to issues. Pick a “last” issue and address that, and start working on the build and promotion cycle. There are a lot of things you can be doing in the background when not working on issues.

Eventually, the user community figures out that everything they want is not going to happen in the first release. One trick a smart PER came up with was to create a “Wish List,” which really was the catch-all for every new enhancement request that came up. The developer focused on entering real defects into the real issues list. A real defect is something that is technically difficult, generally requires a design change, and needs to be approved by the CCB before it is corrected. After all, when a defect is only apparent during certain artificially contrived conditions (like in a training class), it’s not all that big a priority. The key is to push all of these decisions onto the CCB so that they 1) see responsiveness, 2) are involved in the decision making process, and 3) have a sense of control over the project.

Three critical success factors brought the project under control. First, the establishment of the wish list and the issues list created a focal point for the user community. Suddenly all the discussions were about what’s on the list, how well they’re defined, what their priorities are, and when they should be implemented. A collaboration area or discussion board is massively helpful here. Second, the CCB began considering issues, but only those issues that had passed through the analysis phase of the change control workflow. A few last issues were promoted to the 1.0 release, but the vast majority of issues were properly reserved for future iterations. Third, the sponsor, developer, and users became comfortable with the fact that there would be future iterations, and in short order. When a team acknowledges that they’re on a long journey, the sprint mentality melts away.

So, yes, both Eric and Joel are right; you need to control what’s going into your next release. For custom software developers, that next release (and the next two or three) need to be visible on or just over the horizon of the user community. Once you have that vision in place, with issues constantly being evaluated and assigned to future iterations, you will have a user community with an “in it for the long haul” mentality. For most customers, this becomes a never-ending story of tuning and improvement. This never-ending story is why custom software can be so enjoyable and so profitable for everyone involved. When you are a developer with a stable of “long haul” projects in place, you don’t need to do any marketing anymore. The bulk of your work comes from current projects, and happy customers generate referral business for you.

-Z-

Shoot This Engineer

"There comes a time in the life of a project when you have to shoot the engineers and put the dang thing into production."

I heard that saying years ago; I can't find the original attribution because it's been cross-quoted all over the Web, but it really applies to me these days. I've been picking away, tweaking this document, then that document, constantly edging toward perfection but knowing I'll never get there. Meanwhile, other stuff is piling up all around me. So I decided that it's time to shoot the engineer and get on with the next steps.

The bulk of the changes happened because I'm simply a more experienced writer than I was five years ago. The PTTQ is new, and I've significantly beefed up the SQAP and SCMP, but it was mostly better grammar and clearer writing that drove me to micro editing. The current documentation set represents Shell Method v1.1.

The biggest change from Shell Method v1.0 is the redefinition of the life-cycle from a traditional waterfall to an iterative life-cycle inspired by a blend of Boehm's old Spiral with Agile methods. In essence, the iterative life-cycle is "Big Design Up Front," as Joel Spolsky likes to put it, but tightened up to the point where it's more like Lotsa Little Designs Up Front, which gives it more of an Agile flavor than anything else.

The Umbrella documentation set has been released at v1.0. This is the documentation set that comprises all the main reference sections and process definitions for the Shell Method:

• Glossary of Software Engineering Terms
• Software Development Life-Cycle (SDLC)
• Software Configuration Management Plan (SCMP)
• Software Quality Assurance Plan (SQAP)
• Project Team Training and Qualification Plan (PTTQ)

I find it ironic that the first template set to be released on dbtemplates.com is the one set that I hope is purchased the least. In fact, I priced it pretty high (relative to the other document sets) in order to discourage folks from taking that path first. If you're purchasing this set, you're not using shellmethod.com as your process repository anymore, and I hope that won't be the case for most Shell Method developers.

The whole idea behind this effort is to provide an open process and repository so that a community of developers can form around the methodology. Once that happens, we can pool our metrics to form a viable empirical model for database project sizing and estimation. Once we have that, we'll really have something, won't we?

-Z-

Software process and climbing

A while back, I was working my way up a climbing wall when I noticed something that I'd missed all the way back to my days on search and rescue teams: I'm not worried about falling when I'm halfway up a cliff. In fact, I'm not worried about much of anything except the bubble of reality starting at my body and extending about 20 feet. Any more than that, and I'm not concerned. I'm not looking down and going "Wow! I could fall and die!" I'm not thinking about all the moves that got me to my current point, and I'm not worried about all the moves I'll need to make before I get to the top. All I'm thinking about is my current set of holds, and my next few moves.

This may be a key to the problem of adopting formal software processes. The entire picture is incredibly complex. The need to simultaneously manage requirements, specs, builds, tests, schedules, metrics, issues, code, politics, and personnel presents an overwhelming picture. Maybe that's why there's so much resistance to adopting formal processes. Just thinking about implementing the entire picture is like envisioning an entire ascent in detail, and the image of falling comes easily to mind.

When people are executing within a defined process, the route has been planned in advance. The details are different, but the route is the same. The participants are not worried about what has passed and what's in the distant future. They focus on their "bubble," which is the current stage. They know where they've been, and are comfortable in their knowledge that what's coming is clearly defined and familiar. Like the climber, they stay in their bubble, focus on what's happening now, and ignore the rest.

It doesn't have to be Shell Method. Any stable process will produce the same effect. The word needs to get out: People who work within formal processes experience a much more comfortable environment. I believe this is one of the reasons why defects are so much lower than in chaotic development projects.

-Z-

A brief history of Shell Method

Every blog has to start with an initial post, and this one's no different. So, I thought I'd start out with a brief history of Shell Method.

Shell Method has been a pet project of mine since the mid-1990's. In fact, I did my Master's thesis on implementing a software lifecycle management process. Shell Method was first made available during 2000, but dropped off the radar for a couple of years as I focused on other things. Now I'm back, and so is Shell Method.

When I first released Shell Method, I did it in stages, and that's the same way the re-release will go. First comes the umbrella documentation set, then the introductory guidance, followed by the specific guidance for the six stages of the iterative lifecycle. As I release each stage guidance, I'll release the document templates for that stage and also update the example site (BOTS) with completed examples of the templates. Eventually, all six stages will be done.

Why am I going this route? Because most of the bang for the buck comes from the umbrella documentation set and the Planning Stage guidance. The rest is nice-to-have, but can be inferred from the example site. Of course, if you're looking for full CMMI linkage at Level 2, you'll have to wait for the whole suite to come out.

Is this pie-in-the-sky? No. Many applications have been developed with this process over the years, and I've personally managed projects that passed formal audits using Shell Method. I'm basically taking the lessons learned over the past few years and incorporating them into a 1.1 release.

-Z-