Develop Technical Guidelines

Provide guidelines on technology management and engineering practices that are used across the Agency.

Introduction Activities Roles and Responsibilities Artifacts

- A-TARS - A-TARS: Technology Guidelines Descriptions - Ancillary Design Information - AIS Design and Implementation Info. - Technical Architecture Work Plans and Direction - Strategic Analysis and Data - Changes Develop Guidelines Update Guidelines - A-TARS: Technology Guidelines Descriptions - Ancillary Design Info. - Status - Changes - Technical Architecture Team - Other Technical Specialists

Introduction

These activities create and update the Technical Guidelines Reference Set, a place to put Agency-wide technology management and engineering practices and keep them up-to-date. These practices apply to individuals using as well as developing the A-TARS. Tutorial and background information can be provided, when needed. This guidance promotes consistency in the application of the A-TARS, establishing a formal channel to communicate effective Agency-wide practices across the IT projects.

The intent for the A-TARS documentation is that it be packaged and used as reference material. The authors of each section will therefore assume an appropriate level of skill and knowledge by their users. Any assumptions about those skills and knowledge may identify gaps where guidance should be provided. The guidelines in this reference set provide a means to close that gap. This guidance may be used as a basis of training A-TARS users and developers.

Projects (or A-TARS developers) will adapt and tailor these guidelines to their specific situations. Quality assurance functions will provide confidence that these are being appropriately implemented.

Top

Activities

The following key activities are performed:

1. Develop Guidelines. These actions create the guidelines for technical management and engineering life-cycle activities and work-product conventions. Examples of activity-based guidelines are those that cover configuration management, planning, tracking, analysis, design, programming, test, certification, security, or data administration practices. Examples of product conventions are coding standards, modeling notations, or Web authoring guides (such as 508 guidelines (see PL 1998) ). These guidelines may take the form of policies, procedures, templates, handbooks, presentations, or any other useful form. The guidelines are developed by iterating through the following actions:
   • Compile specialty guidelines that address unique aspects of the A-TAR sections. The need for this guidance can be identified during peer reviews ( CMU/SEI 1995) of the various A-TARS descriptions as they are completed. The types of users of the descriptions should be identified and judgments should be made on the assumed level of knowledge and skills needed to apply the description. When a gap is determined between current and new skills and knowledge, a task for producing or updating guidelines can be initiated. Having typical users of the description participate in its review may help identify the guidance needed. Keeping a technical glossary and identifying new terms that are being introduced into the Agency may also help identify areas needing guidance.
   • Develop cross-specialty guidelines for information that is not unique to a particular part of the A-TARS. This may include engineering and management practices for life-cycle activities or specific work products. Coordination among the developers and users of the A-TARS can help identify where overarching guidance is needed.
   • Develop or identify educational materials or training courses where further detailed knowledge can be obtained to use the A-TARS. Additional training may be necessary when a significant knowledge or skills gap exists. This may involve identifying vendors for traditional classroom-based courses, using Internet or computer-based courses, or developing the courses using an in-house training center. In-house development will most likely be needed for process-related skills, as details of procedures will be unique to each organization. Orientation events (briefings) can also be produced as part of the deployment of a release of the A-TARS.

   • Compile, review, and publish drafts and final versions of the guidelines. Formal technical reviews, such as peer reviews ( CMU SEI 1995), can be used to review the guidelines. Typical users of a description can participate to determine whether the guidelines are appropriate to their needs. The individual descriptions should be placed under a version control process to track changes.

2. Update Guidelines. Guidance will continually change. New technologies and approaches will be incorporated into the Agency's inventory, others may be retired. Engineering practices will change as new, more effective techniques are used. The skills and knowledge of the users of the A-TARS will also change. The guidelines must adapt to reflect these changes. As changes are made to the A-TARs, the impact on the guidelines should be evaluated, dependencies should be identified, and changes should be synchronized.

Top

Roles and Responsibilities

The key roles and their responsibilities are as follows:

• Technical Architecture Team. Individuals participating in the development of the descriptions in the other portions of the A-TARS may help author these guidelines, such as those that defined the Services Reference Set providing descriptions on the modeling notation used ( UML). These individuals may come from the Core or Extended Team.
• Other Technical Specialists. These individuals support the generation of the guidelines where they have specific expertise, such as programmers for authoring programming guidelines, Web content designers for accessibility guides, or technical editors and publication specialists. These specialties may be obtained from within the IT division or external (consultants), as needed.

Top

Artifacts

The following information is used or produced by these activities. Templates, examples, and checklists for identifying and documenting items are available through the Additional Resources.

• A-TARS. Draft or final descriptions of all sections of the A-TARS are used to provide source material for the guidelines that are documented in these technology guideline descriptions.
  • Technology Guidelines Descriptions - These descriptions are the main product of these activities, updating the previous version, if it exists.
• AIS Design and Implementation Info. An understanding of the existing engineering and management practices is used when establishing the consolidated guidelines.
• Ancillary Design Information. Information associated with the rationale for the guidelines is retained, as needed. This information may provide background for training users of the guidelines.
• Technical Architecture Work Plans and Direction. These work plans guide the execution of these activities, coordinating the individuals performing these activities with other technical architecture tasks and the IT projects.
• Strategic Analysis and Data. The strategic direction, specifically the decisions to keep, replace, renovate, or build on existing IT assets, guides the choice of what practices to integrate into the guidelines and those to omit as legacy systems are retired.
• Changes. Changes provided to these activities represent those things in the current A-TARS descriptions that must change. Changes for other parts of the A-TARS also can be generated, such as updates to the TRM, boundary, integrated descriptions, services, data stores, networking, or equipment. Those changes would be necessary if practices that affect their description changed (e.g., change in notations).
• Status. Progress and issues in developing the descriptions are forwarded to the management activities to ensure coordination between these activities and other technical architecture and IT project activities.

Top