January 16, 2012

Documentation and configuration management plan - M-9

Identify and manage the documents that are useful and necessary to the project, define the configuration of the product and how it changes

A. Subject

Project phasing generates a multitude of information that documents the history of the project from various angles.

Systematic gathering and updating of this information are essential to the smooth implementation of the project.

All information is recorded in technical, administrative and contractual documents, which constitute the project documentation. To ensure success of the project and limit risks associated with the incorrect use of a document or time lost looking for information that has already been written, each of these documents must be rapidly and effectively available and accessible to all those involved in the project.

The aim of information and documentation management is to define and implement the methods and procedures to manage information that is required and sufficient to ensure project success.

Generally speaking, the principles applicable to a project are recorded in the project Documentation and Configuration Management Plan.

The same principles are applied to software configuration management, when they are developed or used for the project.

This Plan is based on the frame of Appendix A of document "RNC-ECSS-M-ST-40 Configuration and information management". For practical reasons, it is preferable to process the chapters associated with documentation management before those associated with configuration management.

B. Fundamentals

Information and documentation management applies throughout the project phasing. It is therefore advisable to define the management rules for the Plan information/documentation section at the start of phase A.

Regardless of its intervention level, each project team can draw up its own Plan ensuring coherence with the higher level management rules.

The Plan defines:

  • the identification, presentation, saving, distribution, updating, classification and archiving of documents issued and received as part of the project, regardless of their type and media (memo, Plan, fax, e-mail, etc.);
  • the signature circuit (internal) or approval circuit (when subject to external approval);
  • the minimum follow-up rules for document updates (revisable documents) including documents "managed in configuration".
  • minimum configuration management rules, including identification.

 

This method defined based on a standard content ensures that nothing is forgotten and ensures compliance with ECSS requirements.

To draft the Plan based on this model, feel free to delete information that is provided for comprehension purposes only.

C. Typical content

1. General

The general aim of the Documentation and Configuration Management Plan is to describe the identification and management rules for documentation, in addition to the identification and management of the project configuration (indicate the project name). The provisions implemented must guarantee the accuracy, accessibility, reliability, security and rapid availability of all useful information to the various people involved in the project.

In terms of configuration management, this document describes the organisation implemented internally and with regards to partners and/or suppliers, the facilities and services implemented in order to be able to deliver a product for which the design was identified and upgrades managed.

This document applies to all project products during the development phases and, if necessary, product maintenance. This document applies to all products under the responsibility of (name the relevant entity) throughout all project phases.

It is intended for:

  • members of the project, to inform them of the principles, services and drawbacks of configuration and documentation management;
  • all those who provide management support (documentation, configuration and software configuration managers).

 

2. Documentation

2.1 Reference documents

RNC-ECSS-M-ST-40C Configuration and information management

If any, list the other general documents used in the company or activity, regarding documentation and configuration management logic and principles.

2.2 Documents applicables

List local procedures relevant to documentation and configuration including security rules if any.

Name, if any, customers' requirements which give minimal rules to apply in the configuration and documentation management process.

2.3 Terms

List and define specific terms, acronyms and abbreviation used in this Plan.

3. Management

3.1 Organisation

The project organisation and the responsibilities of each individual involved in the project are usually described in an organisation memo.

In this case, do not repeat this information in the Plan, but include in this chapter a reference to the project organisation memo.

3.2 Responsabilities

The Project manager: is responsible for the documentation and configuration of his/her project.

If the workload is sufficient enough, he/she is assisted in his/her management tasks by one or more members of the project team or by experts in the relevant management field.

The Configuration and Documentation Manager: (usual functions, only keep those that are useful):

  • proposes the Plan and updates it, if necessary, during the project,
  • ensures, in terms of the project, application of the Plan and compliance with documentation and configuration management procedures by the team,
  • manages the project library (document database), and, if necessary the configuration management tool.
  • He/she manages the configuration management process
  • He/She checks configuration.

 

The Documentation Officer:

  • is responsible for dispatching and archiving (generally electronically) documents that need to be kept,
  • makes sure that documents can be reached and red over time, without ambiguity concerning the level of acceptance and applicability
  • ensures the preservation of document integrity.

 

The Software Configuration Manager (if necessary):

  • checks (especially the Software Configuration File (SCF) and generation procedures) and ensures availability of each configuration item delivered to the project or developed by the project team.
  • Stores software configuration items delivered or produced, which includes configuration of software source codes, installable product production means and tools as well as the related procedures.
  • is able, if necessary, to generate / compile "installable" software products from the stored software (extracted from reference storage).
  • Delivers, from reference storage, software items to project development team or to customer.

 

3.3 Policy, directives and procedures

This Plan is written in compliance with document RNC-ECSS-M-ST-40C.

List, if they exist, other internal or external drawbacks that apply to this Plan

3.4 Security

The aim is to define the protection levels adapted to the project context. To define the correct level of content, answer the following basic questions:

does the document / information require any restricted access, can it be freely published on the internet and be sent via non-secure e-mail? => if yes, the document is public.

does the document / information need to remain associated with an identified community, does it need to be sent via secure e-mail or an ftps-type exchange server but without requiring cryptographic protection? => if yes, the document is classified access restricted to the project.

Beyond this level, it is important to define, in accordance with the customer, the partner or supplier, the best data protection and exchange means.

In this section, describe the sensitivity levels and protection principles retained.

Content sensitivity is suggested by the author and determined by the decision-making authority,

Good practices:

When a document / item of information needs to be protected, it is important to clearly indicate the level of confidentiality with a stamp or banner.

This level is usually indicated on each page and must at least be in colour on the file cover page.

4. Information / Documentation management

4.1 Document identification

Documents are identified to facilitate project documentation management.

The Plan indicates the identification rules retained for documents produced and received as part of the project.

Correct identification requires:

  • a unique number, a set of characters, or an alphanumeric registration,
  • a version and/or a version date.

 

Good practices:

  • Do not use the year to form the document unique number. The version date is sufficient.
  • Do not use structure acronyms or author initials. Structures may change, and the author of an update (version n+1) may not be the same person who wrote the previous version.

 

Other information required for identification may or may not be used to make up the document reference. This information may be explicit names, acronyms or codes of which the meanings are defined in the Plan. These possible identifiers must be understood by customers or partners and will be used to form metadata for exchange/distribution "Technical Data Packages" (TDP) in accordance with the requirements of document "RNC-ECSS-M-ST-40":

  • project identifier
  • product or tree node identifier to which the document relates
  • document type (Examples: Report, Technical Memo, Interface Control Document, Specification Requirement),
  • name of the company, laboratory, consortium, etc. which issued the document

 

Good practices:

Technical tree nodes or product identifiers must have, when possible, meaning to both internal and external parties. It is better to agree on an identifier beforehand with partners or customers and suppliers to facilitate future exchanges.

4.2 Document format & content

The Plan describes the information systems, the standard formats, the software used to create, review, approve, store, deliver and archive data. It specifies the type of format that prevails in the event of conversion.

Good practices:

  • With regards to the "opposable" or "reference" format, select a standardised PDF type stable and transferable format (PDF/A or B). Keep the other formats to facilitate updates or use (e.g. spreadsheet format).
  • Define a standard presentation for documents, in order to make them consistent and facilitate the work of technical personnel.
  • Do not forget: the person approving a document is responsible for the classification level, distribution, identification, etc. and for content quality.

 

Document drawing and evolution

The drawing up of a document must enable it to be used and classified over time.

A document is updated based on the latest version validated (unless otherwise specified) and saved in the project reference documentation area (and not based on the local copies of authors or their secretariat).

A document comprises the following sections:

  • a cover page that clearly identifies the document and specifies:
    • its reference with its version and version date,
    • its title,
    • its classification (content sensitivity level),
    • other identifying data: project, product, company, etc.
    • the names of authors and approving parties,
    • its status and the signatures of approving parties in the absence of an electronic signature,
    • the applicability (if this information is relevant, specify the models, series, equipment to which it applies, etc.), the link to a reference document managed in configuration.
  • one or more additional pages as required (not required for a Report) comprising:
    • the reference of the contract for external contributions,
    • the contents list,
    • the documents used to draft the document,
    • record of modifications, indicating the substantiation (e.g. CRs/CPs processed) and the nature of successive modifications (e.g. chapters affected),
  • the document body:
    • all pages indicate the same version,
    • modifications made are identified (e.g. using a vertical line in the margin),
  • an up-to-date distribution list or simply the target recipients (distributions may be managed centrally and therefore not involve direct handling of the documents)

 

4.3 Checking and approval process

When not specified in the project organisation memo, the Plan identifies:

  • the project personnel responsible for approving documents that are delivered by a supplier,
  • the approval process and records recording this approval,
  • the technical managers with the authority to process information flows with partners and customers,
  • the processes and records of requests for agreement regarding deliverable documents due to a customer (e.g. acceptance slip, etc.).

 

Prior to official distribution, all documents must be officially approved to guarantee the validity of the information they contain to users.

Internally

All documents are approved in accordance with the delegation rules defined for the project. If necessary describe here, the approval and delegation rules.

Approval must be able to be verified without ambiguity by someone working on the project. Describe the means used to verify approval (e.g. status in a reference area).

With regards to the customer

Any information that affects (updates, modifies, is not compliant, etc.) the customer's reference document used for the project must be review and approved by customer prior to any use. The aim is to process technical (concerning performance, the mission, etc.) and contractual (costs, deadlines, specific conditions) impacts.

The notion of customer must be interpreted broadly. For example, the Scientific Manager of a mission (PI) is a customer.

It is important to keep a record of the customer's approval. Describe the methods used to gain approval and keep records. Remember to provide those involved in the project with access to the acceptance report concerning data previously submitted to a third party.

With regards to a partner

Any information that concerns the shared reference documentation must be read by all parties (e.g. during progress reviews) or be the subject of an approval process between partners. The aim is to prevent the impacts of local changes on a project from being discovered too late.

It is important to make the multiparty agreement official and to keep a record of the agreement.

Describe the record preservation and acceptance mechanisms. Remember to provide access to the data acceptance report to all those involved in the project.

4.4 Information system

This chapter describes the facilities and tools used to ensure the rapid, reliable and, if necessary, secure availability of information for project members.

List at least the documentation management and configuration management tools (including if limited to server repositories).

The internal and external distribution means are described (networks, ftp servers, secure or non-secure e-mail, sending a CD-ROM, etc.).

Remember to deal with the following aspects:

  • access of the project team to project "valid" technical reference documents = all the latest versions of approved documents, developed software, status of life of CR, NCR, waivers, etc.
  • reference document reliability (guaranteed non alteration),
  • recycling of content, especially for updates,
  • preservation of data (archiving and retrieval),
  • mechanisms providing access to sensitive data (classified) and classification duration,
  • preservation times and data destruction methods.

 

4.5 Delivery method

The Plan describes the methods implemented to deliver documents in ISO format limited to space requirements and describes in document RNC-ECSS-M-ST-40 in the Appendix specific to the template to be applied.

The Technical Data Package (TDP) is a zip file including the standardised .xml file containing supply identification data (for documents: reference, title, author, company etc.) and at least the unalterable document files form.

To facilitate the use of TDPs, CNES has drawn up an internal memo providing examples of the use of XML tags and mandatory or highly recommended fields. The CNES Information Systems Division is also able to provide a utility program used to produce them (Smart).

Warning: it is strongly recommended not to transfer without protection through the Internet (unprotected mail or unsecured exchange server) when data are not labelled as public.

4.6 Electronic signature

If the electronic signature complying with the requirements of document RNC-ECSS-M-ST-40 is the standard within the project team, it is important to define the practical provisions to be applied with the customer or partner:

  • Mutual acknowledgement if both are accustom to electronic signature
  • Reliable delivery process for approved documents in other cases.

 

4.7 Actions management

To manage actions, refer to chapter M-12.

5. Configuration management

5.1 General

The purpose of Configuration Management (CM) is to manage the characteristics of a system and its components and therefore its technical description and intentional or unintentional developments and deviations that successively impact this description.

The configuration of a product is all of the characteristics that the project deems necessary and sufficient to control and manage this product. These characteristics are generally managed in documents written from a particular point of view (specification, design, production, use, etc.) of which the scope varies depending on the effective activity of the project on this product (purchase, integration, manufacture, design, etc.).

The configuration concerns both the theoretical description of the product ("applicable configuration") and the effective description of each available example ("applied configuration").

Typical content of these 2 types of configuration:

Applicable configuration ("as designed" product):

  • reference documentation providing the technical definition of the product (specifications, drawings, etc.) in "configured" documents for which updates are officially traced (Change Request (CR)/Change Proposal (CP)).
  • approved departures (updates agreed to - Change Requests validated and launched - typically during Change Review Boards) and not yet incorporated in the configured text.
  • departures accepted prior to production (deviations or waivers).

 

Applied configuration ("as built" product):

  • applicable reference documentation
  • documents describing production and its result: Log Books (LB), End-Item Data Package (EIDP), Configuration Item Data List (CIDL), results and proof of calibration or inspection, etc.
  • non conformances observed between the applicable reference documentation and the actual product :
  • anomalies detected (identified and followed up using non-conformance sheets that may result in corrections, rework, upgrades or waivers);
  • accepted waivers (anomalies not corrected or corrected using a waiver process also referred to as RFW), and any usage restrictions.

 

The applicable configuration management provisions are described in this document. When anomalies are discussed in the project Product Assurance Plan, identify this PAP in the applied configuration section.

In addition to the Plan, in the case of software, do not forget:

  • the list of project configuration items (specify if required the list reference);
  • the specific management and operating procedure(s) for the software implemented within the framework of the project (specify if required the specific procedure reference).

 

5.2 Configuration identification

Principles

A project's success is determined by a succession of stages performed in a controlled way to produce the expected product, and in the event of difficulty, to correct as soon as possible whatever needs correcting without waiting for the difficulties to escalate.

Each stage has:

  • the aim of defining an essential contribution to the project (typically at first technical specification, then technical design, then product or procurement of hardware and/or software, followed by integration and final validation);
  • as its conclusion: the review of its production in order to ensure that the stage is complete, coherent and compliant with expectations (in particular regarding the results of the previous stages).

 

When a stage has been validated, this production serves as a reference for the next stage, and the characteristics to be managed constitute a new reference, which is the starting point for product upgrades for the next step.

Before being able to be taken into account, any change to a characteristic of a product specified or highlighted in this configured reference documentation must be subject to an official change procedure involving representatives from all relevant disciplines, customers or partners, as necessary.

A reference configuration comprises a set of documents, drawings, process plans, requirement matrices, etc.) describing the characteristics of a product to be managed. This set of documents is officially known as the configuration reference, at each key stage of the product's life cycle.

Good practices:

Freeze the first configuration reference at least by the end of phase B of the project.

The reference comprises at least the Specification of Requirement for each configuration item, the interface control files, the technical requirements impacting the design, the manufacture or the coding, performances, conditions of use, etc.

Marking

The marking provisions for hardware and software products are described in the Plan.

Marking must allow a product to be identified without ambiguity, and the definition, manufacture and inspection reference documents to be located quickly. It must be legible, clear, unalterable and impossible to dissociate from the product in question.

The marking provisions must take into account the size of the product and its conditions of use. Take into account any requirements specified by the customer.

Marking usually comprises:

  • the manufacturer's ID,
  • the product's code
  • the model (Part Number),
  • a serial or batch number (Serial Number).

 

The marking of software must be integrated into the product itself, guaranteeing the association product - marking

The software marking fields include:

  • the name of the item,
  • the item version,
  • the Software Configuration File (SCF) which is a standardised file,
  • the marking of source files (ACSII)
  • the marking of binary files (name of executable version),
  • the traceability information box for source files.

 

Good practices:

When software is involved, version name or number is recorded in the traceability information box, which is necessary and sufficient. In order not to complexity configuration management do not include version name/number in the files names of the software items.

Software Configuration File (SCF) contends at least:

  • the version name;
  • the « reference version » name ie the software issue from which the software is modified (issue n-1);
  • the list of technical facts (CR and NCR) implemented or corrected from the reference version (as stipulated above),
  • software's dependencies, libraries and their issues (« external software's » required to enable development, generation/compilation and operation of the software);
  • generation and installation manuels;
  • list of modified, suppressed and added files...

 

Avoid to depend on high level rights (for example root's rights) to generate / compile, install and operate. Even if high right level is convenient regarding development activities, it's a loophole and a risk driven process when it comes to operation and maintenance.

When many files are at stake, it's better to rely on automatic procedures or scripts to apply marking.

5.3 Configuration check

Principle

To guarantee the permanent coherence between the actual status of the product and its configuration reference. To ensure this, it is advisable to initiate an official process to identify, assess, make decisions concerning and carry out the proposed upgrades and update the reference in terms of accepted and applied changes.

Change management

The change management process is described in the plan. The process comprises at least the following stages:

  • formalisation of the change request,
  • agreement concerning the relevance of the request by project management & instruction of upstream and downstream impacts,
  • application approved or not approved. If the application is granted, this involves: updating the product's applicable and/or applied configuration,
  • carrying out the change and its verification.

 

1 - Initialisation

The Change Request (CR) may be issued:

  • from management level, customers or partners => define in the plan the information required and sufficient to characterise a request (list of mandatory fields/sections and additional fields). Make sure that the defined fields are used/relevant for internal requests as well,
  • by the project team internally => prioritise the formalisation by the initiator of the need. Use only the fields that are essential to issue the need (if possible, mandatory fields common with those exchanged with the customer);
  • from a lower level (components or supplier) => define the sections that are essential for exchanges.

 

2 - Agreement concerning the requirement, then Instruction

When an agreement is reach to instruct a change request, the instruction (sometime named Change Proposal ) shall address at least the internal impacts as well as impacts on customers, partners or suppliers for all phases (development, manufacture, series production, etc.) for the 3 main decision-making criteria:

  • technical: performances, upstream and downstream interfaces,
  • costs (development, recurring costs, etc.),
  • deadlines (development, recurrent deadlines, etc.).

 

If external impacts are relevant, it is necessary to reach an agreement with other parties prior to apply the modification related to the CR.

Notes:

  • Change Requests (CR) affecting the customer are also known as class 1 (or major) requests. Others are class 2 requests (the customer may simply be informed).
  • The instruction process is generally based on multiple opinions: remember to describe how the opinions were sought to facilitate the work of the technical instructor.

 

3 - Decision

When the impact of the modification proposal is fixed, the instructor presents the possible advantages, difficulties and options.

The decision whether or not to apply the change is made at managerial level (the project or its customer depending on the nature of the change and/or the project phase.

A decision requiring multi-criteria and multi-partner input is generally made during a change review board.

Agreements, disagreements or third-party opinions concerning CRs with external impacts must be substantiated, formalised and recorded as rigorously as agreements concerning documents subject to external approval.

4 - Application and verification

The implementation and verification comprise a technical task and an update of reference documentation. They cannot always be carried out at the same time or by the same person. It is therefore important to record every step of the process and the work that remains to be done when following up accepted changes.

Anomaly management

Anomaly management is dealt with in chapter AP-17 and complies with document "RNC-ECSS-Q-ST-10-09".

Usually, anomaly or non conformance NC management is addressed throughout Quality Management Plan. If No, use the same frame as DM's one, tacking into account following points:

  • NC are usually unexpected events and referred to as report (NCR) and not as Request,
  • Treatment shall be assessed the same way a request is,
  • It's sometime better to live with a non conformance, but when this NC affects upper or lower level, it's compulsory to inform (lower level) or to seek agreement (upper level). This agreement is commonly recorded through a waiver.
  • Corrected NC are reviewed at Technical Meetings before and after tests at which corrections are validated.

 

Waiver management

The first 3 stages in the life cycle of a waiver are the same as those of a Change Request, with a "customer" or "partner" impact. The main differences are:

1 - Initialisation

Generally speaking, a waiver arises due to an anomaly for which an "accept as is" request is issued by a supplier to his/her customer.

2 - Instruction

The instruction must cover the scope of validity (time and items concerned when several products are involved), physical information and usage restrictions concerning the products concerned.

3 - Decision

This may require the customer's approval.

There is no production and generally, no reference documentation update.

The final waiver status with customer approval is generally "accepted".

Change and waiver forms

It is not necessary to define an actual form. Simply define the sections required for information exchange.

The main fields required for exchanges are listed in the FM4. The aim is to facilitate data relevance and uploading in configuration processing tools.

It is also necessary to define the process recording and formalising requests seeking agreements and acceptance decisions as well.

The signature of each issued form of CR/CP, RFW, NCR is a means and not an aim. Keeping records through explicit reports stating the acceptance status for several technical facts (e.g. review board minutes) is also effective and less time consuming.

5.4 Interface management

The plan describes the principles implemented by the project to notify, to request the approval of customers or partners or to seek the opinion of a supplier each time a change request or an anomaly impacts the "customer" reference documentation or the reference documentation shared with a partner or applicable to a supplier.

The plan also presents the internal notification principles when the project is broken down into distinct products, dealt with by completely different or partially different teams.

5.5 Supply management

The supplies are listed in the Special Technical Terms and Conditions chapter (cf. M-2), the AIT deliverables (cf. I-14), the EIDP (cf. AP-13) and the Log Book (cf. AP-14).

The details being already addressed through specific forms, focus in the plan on the management process and the key points set to make acceptance easy and easy to record and reach:

Acceptance review addressing various aspects as hardware, software, acceptance and qualification tests, measurements, documentation accuracy, including Log Book or Software File Configuration SFC, but also installation, users and maintenance manuals,

Acceptance review gains to be a formal meeting with all the accurate records

5.6 Configuration reports management

The configuration report production system is described here:

This system shall be simple, tailored to the context and easy to use by all those involved in the project. This may be a specific electronic tool, by default a spreadsheet or a file managed by an appointed manager. A record book may also be used if file management is problematic.

To facilitate the creation of log books or configuration files, the configuration reports are processed by configuration items and contained two separate sections:

1) The applicable configuration reference

  • for each approved and configured document, Plan, matrix, etc., at least: title, reference, version and version date;
  • changes approved and not yet integrated in the aforementioned reference: references and titles, if possible the products and reference documentation affected. Their application status in the product (this status forms the link between applicable and applied);
  • accepted waivers: reference, title, description, products affected and in use restrictions or limits.

 

2) The applied configuration reference:

  • anomalies (NC) identified and not yet corrected: reference, title, description, products affected, and if possible potential impacts, criticality, etc.
  • manufacturing and test procedures: reference, title, date, version, template (source procedure) and results obtained (readings, inspection and test records).

 

All information listed in the configuration report must of course be reachable and easy-to-access and to handle by the project team.

5.7 Configuration verification

Describe the provisions adopted to verify the configuration.

These verifications are required to prepare the key steps of the project:

  • reviews: the aim of a review is generally to monitor the progress of a phase and to authorise initiation of the next phase. The configuration report is the initial point of reference for the next phase.
  • Test Readiness Reviews. The TRR identifies and freezes the applicable configuration prior to the commencement of manufacture or tests. This facilitates the subsequent processing of production deviations or anomalies encountered during tests.

 

5.8 Audit

Refer to the provisions described in terms of the QAP, if they exist. If they do not exist, list the frequency and reasoning behind the instigation of audits concerning:

5.9 Technical data management

Refer to the Information System chapter or describe the specific details concerning the management and recording of technical data.

Forms

Activities / documentation

Published in: