Home 
CM Journal Articles SCM Techniques #3
CM Journal Articles SCM Techniques #3
|
 Formal Interfaces and Standards & Requirements
ManagementPatterns are a well-understood concept in software development. Thanks to Steve Berczuk and Brad Appleton, they are a part of the SCM vocabulary as well. So far, the SCM pattern vocabulary is relatively low-level, concentrated on describing repository layout, branching strategy and the like. The techniques discussed here are not patterns—they don't have the required structure, and don't provide prescriptive formulas for implementation. Instead, these are discrete, recognizable methods of software development or software configuration management. Configuration management is a discipline that connects to every single part of the software development process. This means that CM affects all parts of software development, but it also means that every part of the process impacts the configuration management activity of a project. Many of these techniques aren't pure configuration management—if there is such a thing. Instead, they are techniques that have a high impact on CM. Adopting these techniques may help your project overcome certain CM challenges. Making radical changes to address a single CM issue generally isn't a good idea. But understanding these techniques can help you contribute to shaping the future direction of your project. This series will talk about twenty-two techniques, from five categories. Here they are. Ceremonious Techniques
My parallel series on Dimensions of SCM Challenge mentions Formal Interfaces & Standards and Requirements Management this month, so we'll look at those two techniques. Both series have started dealing with areas that have more things to say about them. As a result, these articles are starting to get longer. I hope that's a good thing. On the other hand, I got some push-back from some of my volunteer editors for classifying Requirements Management as a CM technique instead of a separate discipline of its own. In fact I agree that RQM is a separate discipline. But this series of articles is about CM Techniques, and to me that includes anything that you can do to make your (CM) life easier. Pursuing formal requirements management definitely fills the bill for some projects, so IMO it's fair game for inclusion in this series. Formal Interfaces & Standards Standards and interfaces can be a burden or a benefit, depending on who benefits from conformance with the standard. When the standard is externally imposed and compliance is a burden, see the parallel article "Dimensions of CM Challenge #2: Standards and Interfaces & Requirements or Business Demands." In some cases, though, Formal Interfaces & Standards can be an effective technique for adding structure and stability to a project. For our purposes there isn't any difference between an interface and a standard-they're both well-specified constraints on the project. Whatever you call them, adopting an interface or standard partitions the system. In the case of a technical interface, this provides separation between hardware and/or software development teams. A targeted standard like "strict ANSI C syntax" or MISRA will offer some performance and/or quality benefits in exchange for fairly straightforward implementation. A "general" standard like UML 2.0 will provide you with the ability to do something (improve documentation) but may require a more specific local standard (documentation standards, anyone?) to really kick things off. In the case of a process standard, the standard will specify the roles and then specify the separation between them. This separation will tend to slow down parts of your project. In exchange for this, technical standards make it possible to start working parallel on separated modules. Process standards generally cost a little more effort, but provide a defined starting and ending condition. This improved clarity helps team members understand where they are, and provides improved visibility to project management. For example, RUP does a pretty good job of setting expectations on different project members. Knowing who is responsible for what lets a team work more confidently. On the other hand, CMMI may be implemented at such a high level that you never even know it happened, or you may wind up in weekly metrics meetings doing your part for "improved visibility." Another advantage to Formal Interfaces & Standards is reduced coupling. By partitioning the system, either technically or organizationally, it becomes possible for one team to work independently of another. At a technical level, this enables parallel development and reduces interference (and bugs) between parts of the system. Process standards can eliminate ‘political coupling' and provide mutually agreed-upon results for different organizations. ‘Political coupling' can happen when a leader or influential member of one team moves to a different team. While having the expert available to help out can be useful early on, excess involvement can lead to one team dominating or dictating the activities of another. Similarly, when one team predates another, or when one team has more influence or popularity than another, the lines between the teams can blur. Process standards can re-draw the lines between the teams, removing some of the undue influence. When two different organizations are working together, there will naturally be some uncertainty as to where the division between them lies. In a client/vendor relationship, naturally the client and vendor are trying to push work to the ‘other side' of the line. When two ‘technology groups' (mainframe vs. distributed, IT vs. R&D, etc.) are working together, the tendency may be to pull design and architecture decisions away from the other groups. When two ‘functional' teams (development vs. QA) are working together, the tendency will be to disagree over hand-offs, responsibility, and control. In every case, having a mutually agreed-upon specification of the roles and responsibilities of the groups is a benefit. Obviously, the best solution would be a custom-written specification for each scenario, specifying all the circumstances of that particular scenario. But nobody has time for that. Pre-written process standards, and pre-designed interfaces, are enormously helpful for this. It is possible to individually specify some technical interfaces. Even these, where everyone involved is a developer and presumably speaks the same language, can have problems. Most of the time this is because of semantics. Everyone agrees on the syntax and signature of an interface, but it requires some experience (which is frequently lacking when groups are first thrown together, since this is the first time they've worked together) to elaborate what the required order of calls is, and/or what the handling of erroneous or imperfect conditions will be. Formal interface languages exist that can automate or validate some of this work. Some technical and process standards provide an added benefit. By decoupling the parts of the system, they make it possible to begin testing the design or architecture of the system very early in development. Early development of test cases can reduce or mitigate problems with interface specifications, and may significantly reduce the cost of rework by finding problems before too much code is written. (This includes process standards. A team that knows what role it will play in a project can begin working on that role earlier. When the role of the team is unclear, time and effort will be wasted in duplication, or in political bickering.) Formal Interfaces & Standards reduces communications across the boundaries that they impose. This can be an advantage-the reduced communication comes from clarity of purpose and reduced discussion about what to do-but it can also be a disadvantage. If the standards reduce communications between important creative parts of the project, you may be creating a problem. Prematurely imposing a technical interface, for example, can prevent the development team(s) from improving the usage model. This may reduce performance, especially if the interface requires all calls to remain excessively detailed. Imposing a process standard prematurely will definitely slow things down. It's hard to know what ‘prematurely' means, but in general a totally new product design should remain loosely managed for a significant time before attempting to "lock down" the development process. (Part of the motivation behind Agile development processes is to keep development teams unlocked, or loosely locked, for as long as possible.) Imposing standards on a project will increase the development workload. Technical interfaces will require that all of a set of functions be implemented, for example, rather than merely the exact set needed for the project to work. Similarly, imposing a formal process will increase the amount of ceremony in the project. Changing from one formal process to another will change the amount of ceremony-that's on you. But keep in mind that time spent on ceremony is time not spend on development. Some ceremony is a good thing, when it serves to distribute information and improve efficiency. Too much ceremony, though, is just too much ceremony. Another potential disadvantage to Formal Interfaces & Standards is an unfair or unbalanced work load. When a standard is used to partition the project, there is the risk that one of the modules or sub-teams may wind up with an excess amount of assigned work. A technical interface, for example, may be created to divide a database interaction module from the rest of the system. But if the database module simply passes data back and forth, and does nothing to abstract or standardize the application/database interface, then the developers assigned to the database component may wind up playing Freecell while the remaining application developers are stuck with the same set of database problems wrapped in a new set of function names. Likewise, if a process standard partitions a project team-via roles-then one team may wind up with a disproportionate share of assigned work. The key here is to understand that creating (or importing) a standard will partition the project-that's the whole idea-and so it's imperative that the partitions that get created are aligned with the natural divisions of the project itself. Implementing a standard requires, first and foremost, an applicable standard. In the case of technical interfaces this means establishing an agreed-upon interface. For the most part this can be left to the development team. It will fall upon you as a CM specialist to find out about interfaces if there is an organizational component. When a technical interface is also an organizational interface, you will have to document it as part of the CM plan, and set up procedures for negotiating changes to the interface. If your job also includes a ‘build' or ‘integration' component, then you may need to keep track of internal interfaces between sub-teams or between technologies. Depending on the size of your project, you may want to impose formal interface controls. Formal languages, like IDL or UML, can be your friend here. The interfaces themselves should be owned by development. But you need to know when they are changing, since the risk of "collateral damage" (broken builds, HSI failures, etc.) is quite high. Implementing a process standard also requires an applicable standard. It can be harder to know when a standard is applicable, and even harder to make the adaptations required to implement the standard. If you don't already have one, consider hiring a Subject Matter Expert (consultant) to help you with the implementation. The real success or failure of a process standard requires buy-in from the project team, training, and easy compliance. Getting buy-in is a simple (not necessarily ‘easy') proposition: explain the problem, and explain the solution. Losing buy-in is just as simple (and very easy), so you need to be right. Training is one of the more difficult areas. I don't know why, but organizations that will spend tens or hundreds of thousands of dollars on a software package to help implement a process standard will turn around and refuse any attempt to establish a training or compliance program. The word for these kinds of packages is ‘shelf-ware.' Last, and probably most important, is easy compliance. It is very easy to comply with a process standard if it is done for you automatically. Consider the difference that payroll withholding makes for retirement and health-care programs. Before the popularity of IRA and 401(k) withholding, few Americans made a consistent effort to save for retirement. But when it became possible to silently and automatically set aside money for retirement plans and insurance, participation rates skyrocketed. This is "easy compliance." If your process standard is built in to a part of the system that users already know about, they will comply simply and naturally by doing what they already know to do. If your process standard requires a steep learning curve and signing on to a new system in order to comply, expect problems. Costs of implementing Formal Interfaces & Standards vary. A technical interface is usually very low cost, requiring a series of meetings and some development hours. A process standard can range from low to high cost, depending on the amount of reorganization required to comply. Obviously, training and automation will raise the costs. (Not training or automating will raise costs even higher, but they'll be hidden costs. See the "No CM" article.) Implementing a technical standard or interface requires an understanding of the architecture or design of the system. For a system being built from scratch this understanding can be hard to come by, especially if the new system is not in the core specialty of the organization. Failing to understand the problem can lead to an inadequate or wrongly-positioned interface (as in the database example, above). A similar understanding is needed to avoid work load imbalances, as mentioned. Implementing a standard, be it technical or procedural, requires a negotiation to establish the boundaries and fine details of the standard. During the early period after implementation, some kind of update procedure should remain in place to allow for ‘fine tuning.' An additional requirement for technical interfaces is a solid test plan. Part of establishing a technical interface is establishing a division of responsibility. This enables both sides of the interface to proceed independently-one of the key benefits of Formal Interfaces & Standards. When a problem occurs across an interface, it can lead to finger-pointing as each team tries to establish that responsibility for the problem lies on the other side of the interface. A thorough test plan, especially one implemented early in the development cycle, will prevent this. Test cases are a good tool for exploring a technical interface to ensure that it is complete, so this requirement should be relatively painless to satisfy. Requirements Management Requirements Management is, like Configuration Management, a subspecialty of project management. It is a field in its own right and has dedicated specialists, software packages, and the like, all of its own. Categorizing requirements management as a CM technique is a little bit disingenuous-very much like calling configuration management a RQM technique would be. But this is an article about techniques that can help solve CM problems, and the fact is that starting a requirements program, or improving a poorly-performing requirements management process, is one way to fix CM problems. (See "Integrating a Requirements Management Tool into a Software CM Environment," Austin Hastings, CM Journal, Vol. 2, No. 9.) Managing requirements can mean a lot of things. The most basic approach to requirements management is simply to gather the requirements and collect them in one place. (A comparable CM approach is collecting files together in a directory called "rev1.0"-the most basic approach.) Beyond that lies more involved collection and processing of requirements. Beyond even that lies tracking and managing changes to requirements-where RQM and CM come together again. Requirements management can be incredibly useful, which is why it is an entire separate discipline. Writing down and agreeing on the requirements for the project helps to make explicit all the needs of all the stakeholders. At first, this transition from implicit to explicit requirements can be filled with surprises. "Well of course it has to have a telepathic user interface!" Seeing the complete list of requirements can be daunting, but the realization that this list of requirements was exactly what the team had already planned to build helps team members feel invested in the project. Specifying exactly what is required also solves or prevents a number of organizational problems. A formal set of requirements is an elaborate form of technical interface. (See "Formal Interfaces & Standards," above.) When a project has to cross organizational or political boundaries, a set of formal requirements provides a touchstone to help resolve the inevitable disagreements over function or responsibility. Another benefit of documenting the actual requirements for a system is that it helps your team know when to stop. This is one of the key tenets of the Agile software development methods: do what you must, no more. In object programming, the acronym YAGNI, for "You Ain't Gonna Need It," is used to discourage writing more code than is absolutely essential. In fact, this is one area where "requirements" and "interfaces" are at odds with each other. Most interfaces are specified as relatively complete, with functions that may seem logical but aren't required for the project at hand. An "open" function implies a "close," "read" implies "write," etc. But the actual requirements of a system may not agree-a word processor may want to read a competitor's format, but not write that format, for instance. When requirements are being managed in a RQM tool-as opposed to a text file or spreadsheet-there is a strong "database" function available to the team. This means that individual requirements, or possibly sub-items below the requirement level, may be linked to other artifacts in the system. This leads to another strong benefit of formal requirements management: traceability. When requirements have a first-class presence in the system, they can be linked or related to other objects. This includes change requests, work items, and artifact revisions. Once the system is in place, creating the web of traceability links is fairly straightforward-most RQM tools provide this directly. This makes it easy to produce impact reports for proposed changes, and implementation reports for accepted requirements. This kind of visibility improves the efficiency of the project management and QA teams, and makes many regulatory compliance tasks trivial. A minimal traceability implementation will connect from original request to system requirement to detailed requirements to technical change order to implementation. A slightly more complete implementation will also link to test plans, then to discovered bugs, then to rework. It isn't too hard to extend the linkage to follow-on requests. As a result, the team's cost reporting and cost estimation model will improve. Whether or not this is actually a good thing is up to you. (Bear in mind that many shops, particularly IT shops, are very cost conscious.) Adopting Requirements Management means an increase in the amount of ceremony in your project. Requirements gathering, analysis, organization, and traceability are all potentially new phases for your development process. While requirements phases can certainly run in parallel with the development and QA phases of an earlier release, the current requirements need to be close to complete before development starts. Each additional requirements phase is going to bring with it the possibility of extra ceremony: requirements change requests, requirements analysis documents, requirements impact meetings. In addition to the costs associated with extra ceremony, Requirements Management has a high up-front cost. A project that is already under way will have to squeeze the requirements gathering and elaboration phases into an already short schedule. Projects that are past their development stage and into maintenance mode may find the costs higher than their ongoing budget. In these situations it makes sense to spin off the requirements management adoption into an entirely separate project plan. Since the adopting RQM is probably part of a new release for the product, this shouldn't be too difficult. A requirements-based development process tends to incorporate requirements identification throughout the development and testing phases. This is necessary and desirable for traceability and compliance, but too much focus on requirements can constrain or actively hinder the progress of the development and testing phases. If the requirements base is not complete, it can be hard for development or QA to relate their work to a real need (requirement). This has the benefit of keeping the project on track, but the requirements must be complete enough not to prevent useful work. Implementing Requirements Management, even at the most rudimentary level, requires a repository for collecting and uniquely identifying requirements. This can be as simple as using the automated paragraph numbering feature of a word processor (but don't-if you delete one, all the other numbers may change). Traceability requires some kind of linking mechanism-a way of creating "fields" associated with a requirement. Similarly, implementing a change control work flow at the requirement level (requirements change requests, as opposed to engineering change requests) demands another set of "tables," plus fields on the individual requirement to link to the change requests. The upshot of this is that pretty much any foray into requirements management is going to need decent tool support. Writing your own RQM tool is not quite as bad an idea as writing your own CM tool, but there are plenty of vendors with real solutions available. The other obvious requisite for Requirements Management is some kind of formal requirements process. Requirements don't "just happen," you have to allocate time and effort to collecting and updating them. The requirements gathering, refinement, and change control procedures that your process doesn't currently have will all have to be added. These required changes to your process are the likely sticking point for any requirements implementation. Because of the extra schedule time, and because of the need to involve other parts of the organization, adding Requirements Management will directly affect other parts of the organization. Acquiring or developing a requirements solution (buy, don't build!) is an obvious cost of implementing Requirements Management. Figure on spending $30,000 plus $5,000 for every member of your project team with "manager" in their title. (It's a bogus estimate,[1] but it won't be that far off.) The other obvious cost will be the work required to gather, analyze, and refine the requirements. This will be a permanent cost-the process will recur with each release. One final cost will be the additional work items, and/or an alternative paradigm, for describing and decomposing work tasks and defects. Where before you may have created a "task" for a developer to add a particular function, that will change to reflect the possible addition of a new requirement (that demands the particular function) or the requirements-related change control work to establish that the existing requirements are not being met in the absence of the particular function. Looking Ahead I'll try to cover two techniques each month, but there's no fixed order. If you have a particular technique you'd like to have discussed earlier, drop me a line. If you have a technique that I haven't identified, please, please let me know-I don't claim this list is exhaustive. Austin Hastings has spent more than 20 years in the software industry. He has been a developer, system administrator, CM specialist, manager and consultant. Currently he is principal consultant for Longacre, a software CM and process automation consultancy. Austin lives in the southern part of New Jersey (the garden of the Garden State) but travels the world helping to keep software under control. Contact him at Austin_Hastings@Yahoo.com, or through CM Crossroads. [1] In a past life, I worked for a company whose products were always identified with designations like AB-1100 and XYZ-350. As a joke, I wrote a "ROM size estimator" that could take product design documents from the Marketing department as input, and returned an estimate of the amount of ROM needed. The algorithm was based on the knowledge that marketing always reduced features until the XYZ-350 type products fit in a ROM of 2 megabits, while the AB-1100 type products were more expensive, and could then have bigger (4 megabit) ROMs. So the tool searched for the first string that matched either of those patterns in the input, and printed the resulting number along with the caveat that "certain of the ‘extra' features may get dropped for performance reasons." Marketing found out about the tool, and demanded access to it, and so the tool became a standard part of the product development process. Years after I left, I got a call from my replacement offering a consulting contract if I would come in and update the "natural language parser" in the tool, since it was consistently producing low estimates. I let him in on the secret but rather than carry on the tradition of R&D wizardry, he chose to let the cat out of the bag. I take some satisfaction from the fact that the tool had a useful life of nearly a decade, and even more satisfaction from the knowledge that R&D made him perform the ROM size negotiations with the Marketing group himself, since he ratted everyone out. Austin Hastings has spent more than 20 years in the software industry. He has been a developer, system administrator, CM specialist, manager and consultant. Currently he is principal consultant for Longacre, a software CM and process automation consultancy. Austin lives in the southern part of New Jersey (the garden of the Garden State) but travels the world helping to keep software under control. Contact him at Austin_Hastings@Yahoo.com , or through CM Crossroads.
Set as favorite
Bookmark
Email this
Hits: 4713 Trackback(0)Comments (0)
|
| Last Updated on Wednesday, 26 March 2008 06:42 |
TrackBack URI for this entry
Subscribe to this comment's feed