Task: Prepare Guidelines for the Project
This task describes how to prepare project-specific guidelines.
Disciplines: Environment
Purpose

The purpose of this task is to:

  • Harvest existing or develop new guidelines for use by the project.
  • Make the existing guidelines accessible for the project members when needed.
  • Working with subject matter experts to update these guidelines based on feedback from the consumers.
Relationships
Steps
Identify the Project's Need for Guidelines
Purpose: To identify which guidelines are needed by the project.

Based on which work products need to be produced and the formality level required for each work product, identify the set of guidelines needed by the project. Preparing guidelines is considered part of tailoring the process for the project and the process engineer will spend a fair amount of time with the project manager deciding which types of guidelines should be made available to the teams.

Project-specific guidelines serve several purposes, including :

  • To provide prescriptive and relevant guidance on the production of certain work products.
  • To ensure that work products are developed consistently and follow the defined conventions and styles.
  • To describe certain standards required for the project adherence.
  • To provide a precursor for staff reviewing the quality and completeness of the work products.

In the table below some of the most commonly considered guidelines for a software project are described. The RUP comes with examples of these that can be used as a starting point for project-specific tailoring.

Type of Guideline
Role Involvement
Producer(s)
Consumers
Business Modeling Guidelines
Describes how you should model business use cases, business workers, and business entities. These guidelines should be considered when the project needs to formally model the business to build a new system. The degree of business process redesign, or the complexity of the business process, dictates how comprehensive they need to be.

Business Process Analyst Business Process Analyst, Business Designer, Technical Reviewers
Use-Case Modeling Guidelines
Needed whenever use cases will play a significant part in capturing the behavior of the system. Should contain modeling conventions such as relationships to use, styles to follow for textual descriptions.

System Analyst System Analyst, Requirements Specifier, Designer

Design Guidelines
A product of the architecture definition. It describes the guidelines to be followed during design, architectural design, and implementation.

Software Architect Designer, Implementer, Technical Reviewers

Programming Guidelines
Specific to the actual implementation language(s) and class libraries selected for the project. The guidelines should specify how to present code layout and commenting, how to use naming conventions, and how to use language features. They should also describe precautions regarding certain language features.

Software Architect (with the help of key Implementers) Implementers, Testers
User-Interface Guidelines
Should give project-specific rules and recommendations for building the user interface. Often reference external publications, such as The Windows Interface Guidelines for Software Design, by Microsoft® Corporation.

User-Interface Designer User-Interface Designer, Designer, Implementer

Tool Guidelines
Describes how the project makes the best use of the selected tool set. You can choose to provide one guideline per tool. A tool guideline will often includes :

  • Installation information, such as version, configuration parameters,
  • Limitations in functionality, and functionality that the project decided not to use
  • Workarounds
  • Integration with other tools including procedures to follow, software to use, and principles to apply.
Tool Specialist Tool Specialist, Tester, System Administrator, tool users
Test Guidelines
Used to record adjustments (often tactical) to the way the test process is enacted on a given project, and to capture project-specific practices discovered during the dynamic enactment of the test process. Examples of test guidelines are test completion criteria and defect management guidelines.

 
Test Designer Test Designer, Tester, Test Analyst

Note: You don't need to decide on the complete set of guidelines upfront. Often, the need for guidelines and concrete examples is discovered during the work of preparing the environment for an iteration.

Prepare Guidelines for Project Use
Purpose: To make the identified guidelines available ready for the project members.

One important decision to make when analyzing the resulting set of identified guidelines is whether to "Buy or Build". Although you might be able to obtain the guidelines you need for "free", you should always consider the cost of turning the set into a useful guidelines in the context of the project versus the cost of developing guidelines for a specific need, or maybe even skipping these guidelines altogether.

Sub-topics:

Obtain Existing Guidelines Jump to the top of the page

The Process Engineer, who is responsible for the project-specific processes, continuously looks for useful existing guidelines or examples that can help the project members produce higher quality software more efficiently. Some guidelines may exist in the company's asset repository and are often a compilation of "organization-specific practices." Others fall into the category of "public standards" and can be found in existing literature or via the Internet.

Develop New Guidelines Jump to the top of the page

Most guidelines are initially produced as project work products, such as the documentation of some micro-process inside a project, and as with most other assets, someone sees the value of the guideline outside the scope of the project and promotes it as a candidate for reuse.

When the decision is made to produce a new guideline inside the project, make sure it gets proper attention and is treated as an internal project work product. This includes allocating resources to produce and verify it and including it in the appropriate iteration plans.

In the first instance, developing the guideline for the specific context of the project is highly recommended. There exist numerous stories of projects being derailed because of the focus on generalizing work products for future reuse instead of developing them for the specific purpose at hand. As part of the organization's process improvement effort, consider making the produced guidelines reusable for future projects. The work of turning a guideline,or any project work product, into a reusable asset should ideally be accounted for outside the budget of the single project producing it in the first instance.

New guidelines may be developed anytime during the life cycle of the project. They are commonly developed "just-in-time" or as a task to document a successful approach to producing other work products.

Tailor the Guidelines Jump to the top of the page

Guidelines and examples need to fit the context of the project, or they won't be used. Tailoring the guideline to fit the project is the responsibility of the process engineer and some key representatives from the consumers. It is particularly important to make an effort to tailor guidelines that are harvested from other projects, as they may have been developed for a slightly different context.

You should capture any tailoring decisions made as they may prove useful for future projects wanting to reuse the same guideline.

Make the Guidelines Accessible Jump to the top of the page

As important as the tailoring is to the guidelines, the accessibility of the prepared guidelines is equally important. It should be clear to the consumers where they should go to find the guidelines or an example and also to whom they should provide feedback on usage.

You can make the guidelines available via the published process Web site using the RUP plug-in technology, where the guidelines can be associated with the work products and tasks they relate to. See Concept: Tailoring RUP for further information. 

Maintain Guidelines
Purpose: To improve the guidelines based on the consumers experience of use.

In any reuse-focused organization, it is crucial to the process improvement effort that projects provide feedback on their use of assets. Remember that most good practices generally become good because they've been used a number of times before and have had time to be fine-tuned and improved.

When discovering issues with the guidelines or seeing potential improvements, a project has the option to fix the guideline or raise a change request for it to be handled outside the project. Which option to take often depends on the formality of the process effort in the organization and on the complexity of the issue. The Project Manager should consider defining time slots in every iteration to revise and further develop the guidelines as needed. It is often a good idea to provide an easy-to-use forum for team members to quickly record potential improvements as they are identified.

More Information