This website is no longer maintained. Its content may be obsolete. Please visit http://home.cern/ for current CERN information.
The problem
Documents are produced in all phases and activities of a software development cycle, e.g. User Requirements, Design and Architecture, Configuration Management, Test Plan, Project Plan, and so on. The content material required by each of these different document types is very specific - in fact a detailed table of contents, as well as additional guidelines, are normally provided by the standard being followed, e.g. IEEE, ESA, ISO. However, it is generally desirable to have a consistency in the layout (formatting, style sheets, visual style) across all of the specification documents for a software development project.
Separate layout and content templates
The Software Documentation Layout Templates (SDLT), produced in IT/IPT, are a set of generic format templates to be used in conjunction with separate content-only templates, specific to each document type. A content-only template will therefore specify such things as the detailed table of contents, sample material and guidelines for the type of document. The advantages offered by this scheme are:
-
Visual consistency across the various documents for a project can be achieved in a manageable way, and requires the maintenance of only one set of layout templates.
-
Allows for the independent production and maintenance of content-only templates - to add a template for a particular document type will require only the creation of a content-only template. This greatly reduces the effort needed both for adding as well as maintaining new templates.
-
If a content-only template for a particular document type does not yet exist, 3
rd
parties have the liberty and the means to add it, as required by their project.
An example of such a content-only template is the new version of the ESA URD content template, which thus supersedes the last release of the CERN PSS-05 template, Version 2 of 30 June 1998.
Main features of the SDLT
The SDLT are produced for Adobe FrameMaker 5.5, thus usable on various UNIX, PCs and MACs. Features include:
-
FrameMaker book structure.
-
Pre-defined formats for cover pages, front matter, table of contents, automatically updated lists, chapters, appendices, and index.
-
Comprehensive pre-defined formats for all typical software specification documentation material.
-
Automatic generation of structured webs.
-
Comprehensive user documentation.
Working model
The SDLT assume the following working model:
-
Identify the type of document that you need to produce for your project.
-
Choose the appropriate SDLT template, i.e. for longer documents use the book package, for short documents use the single file template.
-
If appropriate or available, choose the content template that will contain sample material and content-specific instructions.
-
Copy the layout templates to a clean directory.
-
Combine the chosen content template for your document with this copy of the layout templates (Section 1.5, "Combining with the content template").
-
Set up the book as desired: one chapter per file, or all chapters in the same file, etc. (Section 1.8, "Adding and deleting chapters").
-
Edit the document, following the content-specific instructions provided with the content template and the layout-specific instructions in this manual.
The different components of the above working model are illustrated in the figure below.
Specific project documents (3) are produced by editing templates obtained by combining the corresponding content template (2) with the software documentation layout templates (1).
|
|
More information and availability
More information about the SDLT package, as well as access to distribution file, can be had from the web pages at:
/docsys/framemaker/templates/sdlt/
Feedback, problems and suggestions
The SDLT are supported by the IPT Group of the IT Division. Please send your problem reports, comments and suggestions to:
DocSys.Support@cern.ch
About this manual
This manual provides the instructions needed to use SDLT, for both the book package as well as the single-file version. It serves as the getting started guide, user's guide and as reference manual for the templates. Although it also contains several FrameMaker-specific tips, it is not a manual for using Adobe FrameMaker - for using FrameMaker please consult the FrameMaker documentation.
Intended audience
The SDLT, and so also this manual, have primarily two user types:
-
The
editor
's role is that of preparing a specific document for a project. It consists of:
-
gathering the required information;
-
organizing it into a cohesive document, according to the type of document, using the predefined formats of the SDLT;
-
managing the FrameMaker files, as well as any other supporting external files;
-
orchestrating the distribution of work and the interaction between the participating editors in the case that there is more than one.
-
The
content template maker
defines and implements new content templates using the layout features of the SDLT, for other editors to use with the SDLT. The content template maker must understand how the generic predefined formats of the SDLT may be used to layout the particular type of content at hand.
Content template makers must also be editors, or at least be fully familiar with their role. In addition, content template makers must define formatting conventions for new type of material, using the predefined layout definitions.
Most of the information in this manual is directed at editors. Chapter 6, "Making content templates", provides the special extra information needed by content template makers.
Glossary
-
Book document
-
A multi-file document, composed of a FrameMaker book file and of several component files, typically one for front matter, one for the table of contents, one or more for the chapters, one or more for the appendices, and one for the index, if any.
-
Book template
-
One FrameMaker book file and the several component template files, one for each type of component.
-
Component file
-
Single FrameMaker file that is part of a FrameMaker book. May be of several types, such as front matter, chapter, appendix, etc. A single component file may contain from one to several chapters (or appendices).
-
Component template
-
Single FrameMaker file containing the formats for a particular type of component.
-
Content template
-
A FrameMaker document containing sample content, and guidelines how to collect, organize and format the information, for a particular kind of software development document, such as a User Requirements Document, Architecture and Design, Test Plan, Project Plan, ...
-
Layout template
-
One or more FrameMaker files that define the formats required for a particular type(s) of component file(s).
-
Project document
-
A deliverable document, produced during the lifecycle of a software development project. May be a single FrameMaker file or a multi-file FrameMaker book.
-
Single file template
-
A template file that includes all the formats necessary for short single-file documents, e.g. formats for the title page, for chapters and appendices, etc. Thus a single-file template is different from a component template as these are streamlined to contain only those formats for a specific part of a long document, such as only for a chapter or only for an appendix.
FrameMaker at CERN 
