Saturday, November 19, 2005

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-

Friday, November 18, 2005

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-