Документ взят из кэша поисковой машины. Адрес оригинального документа : http://www.eso.org/projects/dfs/team/ESO-doc-proc.html
Дата изменения: Fri Jul 29 17:03:19 2005
Дата индексирования: Sun Apr 13 22:48:56 2008
Кодировка:

Detailed procedure for issue of documentation

DFS Department
DFS documentation process

HOME

INDEX

HELP

NEWS

Each document which is originated by a DFS Department member has to be issued according to the following procedure which is consistent with the ESO Technical Archive one.

Submitting a new official issue
Naming document file(s)
Approving the new release
Distributing the new release
Archiving issues of documents
Retrieving previous documents releases
specific procedure for the DMD secretary

Hints for document conversions: FrameMaker to HTML, WORD to PDF, PS to PDF.

Submitting a new official issue

An official issue corresponds to a complete version to be configuration controlled. Draft or incomplete issues of documents are NOT concerned by the following procedure.

For the first official issue:

Retrieve an electronic version of the standard generic ESO document template. For the moment, it's available in MSWORD format and StarOffice format; Framemaker and LaTex will be available soon. Several documents are also available as specific complete templates defined internally for DFS Department documentation (e.g. template for Test Plan, for Test Report, ...). These templates are fully applicable to DFS Department documents. They describe not only the preliminary pages, but also give precise rules and recommendations for filling in each specific paragraph.
Identify the TYPE of document according to the ESO documentation TYPE definition list. It is the responsibility of the author to identify the correct document TYPE.
Identify the Product Structure Code according to the following PSC definition list applicable to DFS Department products. It is the responsibility of the author to identify the correct PSC.
Send an email to the DMD secretary asking for a chronological four-digit number , specifying:
- the document TYPE,
- the PSC,
- the document title,
- author name(s),
- indicate whether the document has to be distributed outside DMD or not.
- indicate whether the document has to be distributed outside ESO or not.

The ESO document official number is then defined as following:
PROJ - TYPE - ESO - PSC - chrono

Example: VLT-SPE-ESO-19100-1836 corresponds to the 1836th document archived for the VLT project. It's a specification document about Proposal/Program handling.

Please, notice that in principle, the DMD secretary is your unique interface for managing documents: in case of absence or further information, please, ask directly the DFS Department QA manager.

For all current DFS Department projects, the official project abbreviation PROJ is "VLT".

for any issue (including the first one):

Include the following information on the cover page of the document:
- Project name (e.g. Very Large telescope)
- Document title
- ESO document number (e.g. VLT-SPE-ESO-19100-1836).
- Issue number (e.g. 23). The issue shall begin at Issue 1 and then go to 2, 3, ... It's thus a chronological number. Intermediate issue numbers such as 1.1 or 1_2_3 are then NOT allowed (no special character such as dot, dash, underscore in the chrono number).
- Issue date (in YYYY-MM-DD format)
Fill in the following fields:
- Record of Changes: this field should contain a precise list of points which are modified, removed or added in the current issue, comparing with the previous one. It is strongly recommended to specify here Action Remedy Problem Reports numbers or action items numbers (extracted from DFS Department To-Do lists).
- table of contents: should always be consistent with the content itself.
- scope: specific paragraph describing the main goal and topics covered by the document.
- list of abbreviations/acronyms
- List of Applicable and Referenced Documents
Fill in the page header information. On every page of the document with the exception of the front page, the following must be specified and appear:
- document title
- ESO document number
- issue number
- issue date (YYYY-MM-DD format)
- current page number / total page number
A complete distribution list shall be included for internal distribution. Up-to-date distribution list forms are available from the DMD division secretary.
For distribution outside ESO, a completed Request for external distribution of documentation form shall be attached. It means that the request has been authorized at Division Head level. Such list is also available from the DMD secretary.

Go to top of page

Naming a document file

File corresponding to a document must be named PROJ - TYPE - ESO - PSC - chrono - Vi.ext where:

PROJ, TYPE, PSC and chrono are defined as above. Be aware, use UPPERCASE only separated by a dash (-) character !
Vi is the Version (=issue) number of the document(e.g. V12).
.ext the extension corresponding to the document editor used (.doc or .dot for MSWord; .htm or .html; ...).

If the document is composed by several files (case of Latex files, for instance), they must be gathered in a single Tar file, since the webcheck tool can handle one file at a time, only.

Usage of compressed format (GNU GZIP) is welcome.

Go to top of page

Approving the new release

For any document which has to be circulated OUTSIDE the DMD division, apply the "three signatures rule". It's the case for instance of any document which have or can have deeper and/or lasting impact on ESO operations, equipment and safety.

the 'Prepared by' area must be signed by the author(s). The author(s) may not approve or release the document.
The 'Approved by' area must be signed by the supervisor of the author. The supervisor may elect to have the approval area signed by the next hierarchical level.
The 'Released by' area must be signed by the Work Package-responsible Division Head.

Go to top of page

Distributing the new release

EVERY original paper copy of a document shall first be passed to the DMD division secretary , who will:

archive the paper copy,
attach a distribution list form,
if the document has to circulate outside ESO, attach the Request for external distribution of documentation form,
send original with form(s) to Technical Archive together for registration and distribution where they will be retained by the Archive.
and update a specific internal DFS documentation list.

In parallel with the original paper version, file(s) related to the document must be archived using the webcheck tool. Usage of this tool is the only mean to guarantee an appropriate management of the document, i.e. an automatic access from the DFS group website.

Not only sources of document have to be archived via webcheck, for instance:

webcheck -in -S VLT-SPE-ESO-19300-1234-V8.tar.gz
but also a read-only version (i.e. a HTML, PDF or PostScript file), for instance:

webcheck -in -R VLT-SPE-ESO-19300-1234-V8.pdf

We recommend the PDF format rather than Postscript, since it's more standard and file size is smaller. Use of HTML is welcome as well, if it gives a nice result. Please, have a look at following links to:

Paper copies of documents shall be distributed by Technical Archive only. The author(s) will always receive a copy of his document.

Draft or incomplete issues of documents are NOT handled neither by the DMD division secretary, nor by Technical Archive: they are not concerned by this procedure.

Be aware that no document will be properly managed if the corresponding file(s) is(are) not archived via the webcheck tool and original paper version not given to the DMD secretary !

Go to top of page

Archiving issues of documents

The DMD secretay archives a paper copy of any delivered document according to:

first, the PSC code
then, the ESO Documentation Type definition
and finally, the chronological four-digit number.

The DFS Department document repository is directly accessible from the DFS Department website. This repository contains: author(s) name(s), the ESO reference number, the title, issue date, issue number and a direct access to corresponding read-only file(s) on the web.

Naming conventions for documents files (see above) must strictly be applied to enable webcheck to properly archive the document issue and make it accessible from the web.

Go to top of page

Retrieving previous documents releases

First, have a look at one of the DFS Department document repository content (there is one repository per PSC). Any official issue previously archived via webcheck as a read-only file - HTML, PDF or PostScript - should be accessible on-line (if your Netscape browser is correctly configured to automatically run tools such as acroread or ghostview) and can thus be downloaded.

Sources of a document can only be retrieved via the webcheck tool: they are not accessible from the web.

If you wish to get a paper copy of any previous document issue, please, ask the DMD secretary.

Technical Archive keeps original versions of documents which are managed according to the current procedure, the DMD secretary always keeping own copies.

Go to top of page

Specific procedure for the DMD secretary

The following and specific procedure has to be followed by the DMD secretary only.

DFS Department DFS documentation process