SPIRE SPIRE

SPIRE

SUBJECT: SPIRE Document Management Plan

PREPARED BY: K.J. King

DOCUMENT No: SPIRE-RAL-PRJ-000032

ISSUE: Issue 1.1 Date: 13

September 2000

APPROVED BY:

K. J. King

Date:

13

September 2000

Distribution

Project

M. J. Griffin QMW

L. Vigroux SAp

K.J. King RAL

D. Kelsh RAL

W.K.P.Gear Cardiff

J-P. Baluteau LAM

C.R. Cunningham ATC

S.D. Sidher RAL

B.M. Swinyard RAL

S. Oliver Sussex

T.G. Dimbylow RAL

N. Todd ICSTM

R. Gastaud SAp

Co-Is

E. Lellouch DESPA

H. Moseley GSFC

I. Perez-Fournon IAC

P. Cox IAS

M. Rowan-Robinson ICSTM

P. Saraceno IFSI

J. Bock JPL

J-P Baluteau LAM

A. Franceschini Padova

P.A.R. Ade QMW

R.J. Emery RAL

G. Wright ATC

P. André SAp

G. Olofsson Stockholm

G. Davis USK

Project Managers

G. Michel DESPA

L. Duband Grenoble

J.M. Herreros IAC

F. Pajot IAS

T. Sumner ICSTM

R. Cerulli IFSI

J. Lilienthal JPL

D. Pouliquen LAS

B. Winter MSSL

P. Andreani Padova

P. Hargrave QMW

K.J. King RAL

I. Pain ATC

J-L. Augueres SAp

H.G. Floren Stockholm

D. Peterson USK

Ch C ha a ng n g e e R Re e c c or o rd d

ISSUE DATE

.01 01/10/98 1

Draft issued internally for comments

0.2 01/02/99 2

Draft issued

1.0 03/02/99 Issue 1.0

1.1 13/09/00 Update to procedure for controlled document

Modified Institute Codes

Table of Contents

1. S COPE ...6

2. D OCUMENTS ...6

2.1 A PPLICABLE D OCUMENTS ...6

2.2 R EFERENCE D OCUMENTS ...6

3. I NTRODUCTION ...7

4. DMS ...7

4.1 DMS L OCATION ...7

4.2 A CCESS S OFTWARE R EQUIREMENTS ...7

4.3 DMS DOMAINS ...7

4.4 A CCESS C ONTROL ...8

4.5 D OCUMENT I NFORMATION ...8

4.6 N OTIFICATION ...9

5. D OCUMENT G UIDELINES ...10

5.1 D OCUMENT I NDEX INFORMATION ... 10

5.1.1 Filename [optional] ...10

5.1.2 Viewer [Mandatory] ...10

5.1.3 Issue [Mandatory]...10

5.1.4 Access Level [Mandatory] ...10

5.1.5 Document_Class [Mandatory]...10

5.1.6 Title [Mandatory] ...11

5.1.7 Doc_Code [Optional]...11

5.1.8 Issue_Date [Mandatory] ...11

5.1.9 Ref_Code [Mandatory] ...11

5.1.10 Authors [Mandatory]...12

5.1.11 Abstract [Optional]...12

5.1.12 Comments [Optional]...12

5.1.13 Pub_Info [Optional]...13

5.1.14 Custodian [Mandatory]...13

5.1.15 Cust_email [Mandatory]...13

5.1.16 Keywords [Optional] ...13

5.1.17 Originator [Optional]...13

5.1.18 Recipient [Optional] ...13

5.1.19 Submitted_by [Mandatory]...13

5.1.20 Subm_Email [Mandatory]...13

5.1.21 Full_URL [Optional] ...13

5.1.22 Subm_Date [Mandatory]...13

5.2 D OCUMENT F ORMATS ... 13

5.2.1 Documents shall be added to the DMS preferably in approved formats. ...13

5.3 R ESPONSIBILITIES ... 14

5.3.1 All documentation added to the DMS will be maintained by a custodian. ...14

5.3.2 Documentation will always be added to the FIRST/SPIRE/Internal domain ...14

5.3.3 Users shall use document templates ...14

6. C ONFIGURATION C ONTROL ...14

Glossary

ASCII

DMS Document Management System

ESA European Space Agency

HIFI Heterodyne Instrument for FIRST HTML HyperText Markup Language

FINDAS FIRST Integrated Network and Archive System FIRST Far Infra-Red and Sub-millimetre Telescope FSC FIRST Science Centre

PACS Photoconductor Array Camera and Spectrometer PDF Portable Document Format (Adobe)

RAL Rutherford and Appleton Laboratory, Oxfordshire, UK SPIRE Spectral and Photometric Imaging REceiver

TBW To Be Written

1. S COPE

This document describes the way in which the documentation for the SPIRE instrument will be managed through the instrument development and implementation phases and during operations.

It has been recognised that it would be useful to keep the entire FIRST project documentation in one system, to allow a common management philosophy and also easy access by all the teams working on the project. The FIRST Science Operations Concept and Ground Segment Document (RD1) envisaged that the FINDAS system would be used for this task, however, FINDAS is not yet developed.

Until FINDAS becomes available it is necessary to put in place an alternative system and it has been accepted that the ESA Space Science Department Document Management System (DMS) would be acceptable in this role, at least until FINDAS comes on line. This plan therefore covers the management of the SPIRE documentation, as it will be carried out using the DMS. A later version will be issued when the FINDAS system becomes available.

2. D OCUMENTS

2.1 Applicable Documents

AD1 FIRST Science Ground Segment DMS Document Policy (TBW)

AD2 FIRST Science Ground Segment DMS Document Procedures (TBW)

2.2 Reference Documents

RD1 FIRST Science Operations Concept and Ground Segment Document (SPIRE-ESA-DOC-000186 Ref. PT-03056)

RD2 A DMS Primer

([DMS_info] No.0000006)

RD3 SPIRE Procedures for Document Management

(TBW)

3. I NTRODUCTION

It is important that the documentation produced during a project is adequately managed; that all documentation is recorded and archived; that all documentation can be found and accessed easily by those authorised to do so and that the project formal documentation is controlled so that everyone is aware of the latest version. This task will be carried out by a combination of the use of the facilities of the ESA Documentation Management System (DMS) software and the set of guidelines for its use by the SPIRE project given in this document. The procedures for managing the SPIRE documentation are described in RD3.

The next section gives a description of the ESA Documentation Management System (DMS), the facilities it can provide and the way in which they shall be used by the SPIRE consortium. The SPIRE Document Management scheme will comply with the FIRST Science Ground Segment DMS Document Policy (AD1) and the FIRST Science Ground Segment DMS Document Procedures (AD2).

Section 5 provides the guidelines for the handling of the different document types to be managed by the system.

Section 6 describes the configuration control to be applied to the formal project documents.

4. DMS

This section gives a brief overview of the DMS system provided for FIRST/Planck (DMS is customisable for different projects). For a fuller explanation refer to the DMS Primer (RD2).

The main purpose of DMS is the “circulation” of documents (as opposed to use of mail/email/fax/etc.) rather than their “production”. (It provides no help for control of updates to documents from multiple authors and does not allow multiple-file documents etc.) It provides a repository for documents, such as satellite specifications, interface documents, technical notes etc, so that they are always available and accessible from a known place.

4.1 DMS Location

Currently DMS is located on a central server, located outside the firewall at ESTEC, which allows access to, and retrieval of, documents via a WWW browser interface. In the case of slow Internet links to ESTEC it is possible to replicate the database at other sites and keep these updated regularly (e.g. twice per day).

Initially the SPIRE documentation will reside on the ESTEC DMS server. If it is found that performance is inadequate then the database may be replicated at RAL.

4.2 Access Software Requirements

The DMS system relies on the use of javascript for display of information and interaction with the user. Although both Netscape and Internet Explorer (version 4 or later) work for searching the DMS, it has been found that, currently, Netscape is more reliable when it comes to reading/retrieving documents. (With the release of Adobe Acrobat version 4.05, IE5 is now able to display PDF files correctly)

Most documents will be held in Adobe Acrobat (PDF) format and a reader is required to open and print the documents. This can be obtained free from Adobe (www.adobe.com) and can be automatically invoked by the web browser when a document link is selected.

To generate Acrobat files from applications Adobe Acrobat is required.

4.3 DMS domains

The DMS system holds the documents it contains in a set of ‘domains’. Each domain has an associated list of

users, each with different privileges, such as the ability to read or write documents to the domain, and an access

level.

For each significant group or activity associated with FIRST (e.g. instrument, FSC etc) there will be two domains created. One of these domains will be accessible by everyone involved in FIRST and the other will only be accessible to those persons involved in the particular group. Initially the following domains have been implemented for FIRST use:

• FIRST/FSC

• FIRST/FSC/Internal

• FIRST/PACS

• FIRST/PACS/Internal

• FIRST/SPIRE

• FIRST/SPIRE/Internal

• FIRST/HIFI

• FIRST/HIFI/Internal

• FINDAS

• FIRST-Planck

• FIRST-Planck/Internal

(The FIRST-Planck/Internal domain is actually implemented on the DMS system inside the ESTEC firewall, and copies of relevant documents are made to the FIRST-Planck domain outside, as required. The effect is the same as the other ‘Internal’ domains).

4.4 Access Control

For each domain a responsible person (and for convenience a second person, for example a secretary or assistant) will be appointed to set up the domain and maintain it. He/she will supply the DMS administrator with a list of the users for that domain and maintain it and other aspects of the domain.

The SPIRE domain responsible persons shall be:

K.J.King (RAL) J.A. Long (RAL)

All members of the SPIRE consortium will be granted read access to the ‘external’ domains (including the FIRST/SPIRE domain) and read/write access to the FIRST/SPIRE/Internal domain. (Read access allows documents to be searched for and extracted. Write access allows a document to be created or updated in the database.)

Each document that is placed in the database has an associated access level (between 0 and 100). By default this is set to 30 and should normally not be changed. Each user with access to a domain (read or read/write) also has an associated access level. If their access level is greater than that of the document, they have access to that document.

All users of the FIRST/SPIRE and FIRST/SPIRE/Internal domains will be assigned an access level of 50. Thus, by default, all SPIRE users will have access to all documents in the SPIRE domains.

In addition, the domain responsible persons will have an access level of 100 and read/write access to the SPIRE domain.

4.5 Document Information

Each document stored in the database has an associated ‘index card’, containing information, such as ‘author’,

‘title’, ‘reference designation’ etc. which is also held by the database. This information is entered at the time of creation of the document (though it may be updated later). It is (usually) the information on the ‘index card’, which is used in the search for documents in the database. For this reason it is important that these fields are filled in with as much relevant information as possible and in a standard format.

Different versions of a document are stored under the same ‘index card’. By default the latest version of a

document is returned when a document is requested. Earlier versions may be requested, if necessary, provided

they have not been deleted from the database.

4.6 Notification

When a user adds a document to DMS domain, all users with access to that domain are notified, by email of the

existence of the new document. This facility can be disabled by users, if required.

5. D OCUMENT G UIDELINES

The FIRST/SPIRE/Internal domain is available for dissemination of information around the consortium. Only consortium members have access to this domain and to allow maximum ease of information flow, all SPIRE

consortium staff will be able to create documents in this domain. However, in order to make the database useful to everyone, it is necessary that a few guidelines are followed in the creation and maintenance of documents.

5.1 Document Index information

When documents are inserted into a domain a certain amount of information is requested to allow indexing and searching of the database. Some information is mandatory, other information is optional, but will allow for easier use of the database if provided. The following fields are requested:

5.1.1 Filename [optional]

The filename of the document you want to submit into DMS, most conveniently entered by browsing the file system on your machine and selecting.

Note: there is a problem with filenames containing blanks. You should ensure that the filename does not include any.

5.1.2 Viewer [Mandatory]

Choose based on the file type (see section 5.2.1). If no file is to be stored 'no file' should be selected. This allows a document number to be reserved for a document before it has been completed. The 'index card' may be updated with the Filename and Viewer at a later date.

5.1.3 Issue [Mandatory]

This is a text field denoting the version number of a document. The following conventions(s) should be followed (it is up to the author to ensure that version numbers follow a sensible scheme (e.g. increasing with time). DMS does not check this):

• The version number has the format "I.R".

Where I is the issue number and R the revision number

• For draft versions of an issue, the issue number is followed by the letter "D" and a draft number, in parentheses. E.g. the first draft of Issue 1 would be denoted as 1.0(D1)

• The initial drafts of a document may use issue numbers less than 1.0, without the need to identify them as drafts:. E.g. 0.1 0.2 0.3 etc.

• The first issue has version number 1.0

• Subsequent minor revisions have increasing minor number . E.g. 1.1 1.2 1.3 etc.

• Subsequent issues have increasing issue number. E.g. 2.0 3.0 4.0 etc.

5.1.4 Access Level [Mandatory]

Leave as the default value

5.1.5 Document_Class [Mandatory]

This is selected from a drop-down menu:

ART = An Article or published Paper COM = Communication (mail/fax) DOC = Document

DWG = Drawings MAG = Meeting Agenda MEM = Memorandum

MHO = Handout/Viewgraphs from meetings

MOM = Minutes of Meeting NOT = Technical Note

OTH = other, for everything that does not fit any of the other criteria.

PHT = Photographs

PRJ = Controlled Project Documents. These will be under configuration control, when issued. (See section 6) REP = Report

TMP = Template (document template, usually MS Word97 format) The Document class forms part of the Reference Code.

5.1.6 Title [Mandatory]

The title is the prime field for searching. It may contain any text.

The following title formats should be used for specific types of document:

Meeting Agenda “Agenda for XXXXX meeting, at YYYYY, ddmmmyy”

Where: XXXXX = meeting title YYYYY = institute or location

ddmmmyy = a date in the form 21Feb98, or 20Feb98-22Feb98 Meeting Viewgraphs “Viewgraphs for XXXXX meeting, at YYYYY, ddmmmyy”

Where: XXXXX = meeting title YYYYY = institute or location

ddmmmyy = a date in the form 21Feb98, or 20Feb98-22Feb98 Meeting Minutes “Minutes of XXXXX meeting, at YYYYY, ddmmmyy”

Where: XXXXX = meeting title YYYYY = institute or location

ddmmmyy = a date in the form 21Feb98, or 20Feb98-22Feb98

Reports “TTTTTT Report for YYYYY, mmmyy”

Where: TTTTT = type of report (e.g. “Progress”) YYYYY = institute or location

mmmyy = a date in the form Feb98, or 20Feb98-22Feb98 Document Template “Template for DDDDDD, FFFFFF”

Where: DDDDD = Document type (e.g. “SPIRE Technical Notes”) FFFFF = Template format (e.g. “MsWord97” )

5.1.7 Doc_Code [Optional]

These are selected from a drop-down menu. Choose the most appropriate code for the document, or leave blank.

5.1.8 Issue_Date [Mandatory]

Use the date of issue of the document (this may not be the date of insertion of the document into DMS).

5.1.9 Ref_Code [Mandatory]

All documents placed in the SPIRE domains will have a unique reference designation, which is consistent with the

FIRST/Planck convention for document numbering. These designations shall have the following format:

FIRST-SPI-ttt-nnnnnn; for the FIRST/SPIRE domain SPIRE-iii-ttt-nnnnnn; for the FIRST/SPIRE/Internal domain

Where:

ttt = document class, i.e. MOM, DOC, ART, etc;

iii = the institute producing the document (except in the case of a reference document):

ATC – Astronomy Technology Centre, Edinburgh DES – Observatoire de Meudon (DESPA)

SBT – CEA, Grenoble

GSF – Goddard Space Flight Centre, Maryland IAC – Instituto de Astrofisica de Canarias, Tenerife IAS – Institut d’Astrophysique Spatiale, Orsay

ICS – Imperial College of Science, Technology and Medicine, London IFS – Instituto di Fisica dello Spazio Interplanetario, Rome

JPL – Jet Propulsion Laboratory, Pasadena

LAM – Laboratoire d’Astrophysique Spatiale, Marseille MSS – Mullard Space Science Laboratory, Surrey PAD – Padova Observatory, Italy

QMW – Queen Mary and Westfield College, London RAL – Rutherford Appleton Laboratory, Oxon SAP – Service d’Astrophysique, Saclay STK – Stockholm Observatory, Sweden SUX - University of Sussex

UCF - University of Cardiff

USK – University of Saskatchewan, Canada

ESA – Documents produced by ESA - a more up-to-date version may be found on other DMS areas.

PAC – Documents produced by PACS - a more up-to-date version may be found on other DMS areas.

HIF – Documents produced by HIFI - a more up-to-date version may be found on other DMS areas.

REF – Reference documents, produced by institutes outside the consortium.

nnnnnn is a unique sequence number within a given domain (thus, in fact, knowing the domain and the number uniquely defines a document, the reference actually provides more information). This number can be obtained from the DMS system when creating a new document (each document (including each version of a document) added to a domain are assigned a unique sequence number, within that domain, by DMS. This number is shown on the

“index card” for the new document as it is being filled in (the 'ChronoNo') and can be copied into the Ref_Code field.).

It is not possible to find the 'ChronoNo' that will be assigned to a document before it is created. If it is necessary to include the Ref_Code in the document (for example in a header) the “index card” can be created without storing a file into the database and the file added later.

5.1.10 Authors [Mandatory]

The list of authors should be given in the following form (to provide consistency of names, when searching):

J.K. Bloggs, A.B. Smith.

5.1.11 Abstract [Optional]

This can contain any relevant text.

5.1.12 Comments [Optional]

This can contain any text. This is the place to record any other reference numbers by which this document is

known.

5.1.13 Pub_Info [Optional]

Information of where else the document may have been published, e.g. a journal or conference proceedings

5.1.14 Custodian [Mandatory]

The holder of the original document. See section 5.3.1 The format of the name should follow section 5.1.10

5.1.15 Cust_email [Mandatory]

The email address of the custodian.

5.1.16 Keywords [Optional]

In order to perform simple efficient searches (because one does not always remember titles, and not all documents about a given topic may have a common word in their titles) a small number of keywords will be used to identify the contents of the document

Select the keywords that is most appropriate.

5.1.17 Originator [Optional]

The group to which the authors belong. Usually 'SPIRE/Consortium'

5.1.18 Recipient [Optional]

The group for which the document was written.

5.1.19 Submitted_by [Mandatory]

The name of the person inserting the document into the database.

The format of the name should follow section 5.1.10

5.1.20 Subm_Email [Mandatory]

The email address of the person identified in 5.1.19.

5.1.21 Full_URL [Optional]

The URL 'associated ' with the document. It could be the Web page of the Author or his/her Institute

5.1.22 Subm_Date [Mandatory]

This is the issue date of the document being inserted into the database. It is filled in by DMS. Do not change it.

5.2 Document Formats

5.2.1 Documents shall be added to the DMS preferably in approved formats.

This will ensure the maximum number of users can read the document. The approved formats are:

ASCII Text files

Adobe Acrobat (PDF) files

HTML files

The SPIRE project Office at RAL can convert MS Office, MS Project, postscript and other formats to .PDF, if required. It is also possible to scan in and (sometimes) use Optical Character Recognition (OCR) to convert paper documents to an electronic form.

If any other formats are used, there is a risk that other DMS users will request paper copies from the custodian, if they do not have the ability to read the document.

5.3 Responsibilities

5.3.1 All documentation added to the DMS will be maintained by a custodian.

The custodian is usually the author, or principle author of the document and is responsible for keeping a copy of the document in its original format(s). The custodian shall be identified in the DMS “index card” for the document.

As it is possible for others to delete the DMS document by mistake, it is important that the custodian keep a copy of the document so that it may be resubmitted. The Project Office, at RAL, will act as custodian, if required and provided with the relevant files.

5.3.2 Documentation will always be added to the FIRST/SPIRE/Internal domain

By default, the SPIRE consortium will use the FIRST/SPIRE/Internal domain for document distribution. The FIRST/SPIRE domain will be used only for documents to be made available for users outside the consortium. This includes formal project documents, project status reports etc. The issue of these documents will be controlled, by restricting the write access to the FIRST/SPIRE domain to the domain-responsible persons. Thus all ‘external’

documents will be placed in the DMS database by the Project Office. The custodian may be located anywhere.

Any request to have a copy of an internal document put into the external domain, should be sent to the SPIRE Project Office. The custodian will be notified that the copy is to be made, so that he/she may make sure that any updates to the internal copy are reflected in the external copy.

5.3.3 Users shall use document templates

Certain document types (Minutes of Meetings, Technical Notes, Project Documents etc) should be written using templates provided for this purpose. This gives a common look-and-feel to the project documentation. The SPIRE templates will be made available in the FIRST/SPIRE/Internal domain.

6. C ONFIGURATION C ONTROL

The document class ‘Document’ shall be reserved for controlled Project Documents. These shall be maintained under configuration control by the SPIRE Project Office and will be issued on the FIRST/SPIRE domain. Thus only the Project Office will be able to issue these types of document.

The sequence for control of project documents is:

1. The author writes the document. (He/She may circulate it among the relevant people or place a draft on the FIRST/SPIRE/Internal domain, for comments.

2. The author sends the document to the Project Office with a request to issue it.

3. The Project Office will ensure that

• The issue number and date have been updated accordingly.

• The document change record has been updated.

And will, if necessary, create a version of the document in an approved format (e.g. PDF).

4. The Project Office sends the document to the approval list with a request for approval.

5. On receipt of approval from ALL on the approval list, the document is issued by placing it in the FIRST/SPIRE domain and notifying the distribution list, by email. The emails of approval will be retained

The Project Office will be the custodian of controlled documents.