S1000D basic TRAINING GUIDE

UNDERSTANDING S1000D ISSUE 4.0(the international specification for technical publications

utilizing a common source database)

PROVIDED BY LOGSA FOR THE U.S. ARMY

Distribution Statement A. Approved for public release; distribution is unlimited.

TABLE OF CONTENTS

MODULE 1 - TRAINING OVERVIEW 1The Training Approach 1The Guide’s Contents 1A PowerPoint Presentation for the Classroom 2

MODULE 2 - INTRODUCTION To S1000D 3Definition of S1000D 3How S1000D Evolved 3S1000D and the Army 4New Terminology 4The Modular Approach 5Data Modules: The CSDB Building Blocks 7Why Programs Are Choosing S1000D and Why the Army is Implementing S1000D Policies to Support Them

8The Main Changes with S1000D 10Using the Full Specification When It’s Needed 11Summary 13

MODULE 3 - THE ESSENTIALS: DMs and Other CSDB Objects 14The Common Source DataBase (CSDB) and How It Works 14The CSDB Objects 15The Data Module 16Types of Data Modules 17Use of XML and Schemas 19The Data Module Code (DMC) 20Publication Modules Codes 22Summary 26

EXERCISE OPPORTUNITIES 27MODULE 4 LAYERED DECISIONS: THE BUSINESS RULES 30

How Business Rules Work 30S1000D Decision Points 31Joint Service Business Rules 32Army Business Rules 33Project-Specific Business Rules 33Generating and Sharing Business Rules 34Documenting Business Rules 36SUMMARY: 38

EXERCISE OPPORTUNITY 39MODULE 5 - S1000D AND THE ACQUISITION PROCESS 41

Introduction 41Verifying that S1000D is Appropriate 41

ii

Deciding on an IETP and the Use of the Functionality Matrix 42The S1000D Functionality Matrix 42S1000D-Required Material to Be Provided in a TMCP 48Contractor Deliverables Related to S1000D 49Standards, Specifications, and Policies That Apply with S1000D 51Summary 52

MODULE 6 - REQUESTING A CHANGE 53Introduction 53The Land WG Process to Change S1000D 53The MIL-STD-3031 Change Process 56

APPENDIX A - AN EAGLE’S-EYE VIEW OF THE ENTIRE S1000D SPECIFICATION58

Introduction 58S1000D Front Matter 59Chapter 1 - Introduction to S1000D 59Chapter 2 - Documentation Process60Chapter 3 - Information Generation 60Chapter 4 - Information Management 65Chapter 5 - Information Sets and Publications 67Chapter 6 - Information Presentation/Use 68Chapter 7 - Information Processing 68Chapter 8 - Standard Numbering Systems, Information Codes, and Learn Codes 69Chapter 9 - Terms and Data Dictionary 70

iii

ACRONYM DEFINITIONS

Acronym Definition

ACAT Acquisition Category

ACT Applicability Cross-reference Table

ADL Advanced Distributed Learning

ADWG Augmented Documentation Working Group

AECMA Association Européenne des Constructeurs de Matériel Aérospatial/The European Association of Aerospace Industries

AIA Aerospace Industries Association of America

ASD AeroSpace and Defence Industries Association of Europe

ATA Air Transport Association of America

BR Business Rule

BRD Business Rule Decision

BREX Business Rules Exchange

CCT Conditions Cross-reference Table

CDRL Contract Data Requirements List

CONOPS Concept of Operations

COTS Commercial off-the-Shelf

CPF Change Proposal Form

CPSC Customer and Product Support Committee

CSDB Common Source Database

CSL CSDB Status List

DC Disassembly Code

DCV Disassembly Code Variant

DDN Data Dispatch Note

DID Data Item Description

DM Data Module

DMC Data Module Code

DML Data Module List

DMRL Data Module Requirements List

DMWR Depot Maintenance Work Requirement

DOD Department of Defense

DTD Document Type Definition

DWG Documentation Working Group

FOSI Formatted Output Specification Instance

IC Information Code

iv

Acronym Definition

ICN Information Control Number

ICV Information Code Variant

IETM Interactive Electronic Technical Manual

IETP Interactive Electronic Technical Publication

ILC Item Location Code

ILS Integrated Logistics Support

IPD Illustrated Parts Data

IPR In-Process Review

ISO International Organization for Standardization

IT Information Technology

JS Joint Services

LCMC Life Cycle Management Command

LMI Logistics Management Information

LOGSA Logistics Support Activity

LSA Logistic Support Analysis

LSAR Logistic Support Analysis Record

MICC Materiel Item Category Code

NMWR National Maintenance Work Requirement

OSD Office of the Secretary of Defense

PCT Products Cross-reference Table

PDF Portable Document Format

PLCS Product Life Cycle Support

PM Project/Program Manager

PMC Publication Module Code

PWS Performance Work Statement

QA Quality Assurance

SC S1000D Steering Committee

SCORM Shareable Content Object Reference Model

SDC System Difference Code

SGML Standard Generalized Markup Language

SI International System

SNS Standard Numbering System

SOO Statement of Objectives

SOW Statement of Work

STE Simplified Technical English

TM Technical Manual

TMCP Technical Manual Contract Package

v

Acronym Definition

TNA Training Needs Analysis

TPSMG Technical Publications Specification Maintenance Group (functions now performed by the S1000D Steering Committee)

XML eXtensible Markup Language

vi

MODULE 1 - TRAINING OVERVIEWWelcome to your S1000D training guide. S1000D is being implemented as an alternative standard for Army publications. In some instances, there are possible downstream benefits with using S1000D. LOGSA is providing this material to introduce Army personnel to S1000D. It is designed for two main groups of people: those who are responsible for procuring technical manuals, and those who are responsible for producing technical manuals. Much of the information will apply to both groups, but some will apply to only one or the other. Exercises are available to help you make sure that the trainees understand how the new approach works, and how to use it.

Please note that this is NOT an Army Training and Doctrine Command (TRADOC) training course. Logistics Support Activity (LOGSA) is providing this material simply to assist any Army command and the associated staff who need to introduce less experienced personnel to S1000D.

The Training ApproachThe S1000D specification is a huge document, and it is pretty intimidating even for experienced Army authors (or acquisition professionals). LOGSA recommends that classroom presentation by an experienced person plus some exercise completion (and reading this guide, if so inclined) is the best way to introduce someone to S1000D’s underlying concepts and their application. This training material is designed to provide introductory and beginner information first before going deeper into more advanced topics. Once an individual is comfortable with the concepts and their application, he/she will be able to navigate around S1000D as more detailed information is sought, such as information about a particular eXtensible Markup Language (XML) element or attribute. This guide will provide you with more detail than the classroom presentation and can serve as a first-level reference manual as well.

The Guide’s ContentsHere are the sections you will find in this volume. The training slides parallel them.

Module 1 Training Overview. An introduction, along with some explanation of the different modules, their contents, and their objectives.

Module 2 Introduction to S1000D. What this international standard consists of, how it evolved, and how/when this approach may be beneficial.

Module 3 The Essentials: the Common Source Database and the Data Module. The real meat begins here. The Common Source Database (CSDB) and the data module (DM) are the essential concepts underlying the modular, electronic-database approach to documentation.

Module 4 Layered Decisions: the Business Rules. One feature of S1000D is that it is designed to be tailored. All decision points related to a document are addressed through business rules that become part of the contract. This section describes how they work and introduces all the levels of applicable rules: S1000D, Joint Service, Army, and project specific.

1

Module 5 S1000D and the Acquisition Process. Content selection matrices and a functionality matrix (for IETP, the S1000D term for IETM) are used to specify most of the document’s characteristics. This section describes the matrix and its use; it also reviews the changes in what goes into the TM Contract Requirements package, what the contractor deliverables are, and which standards and policies apply.

Module 6 The Change Process. The processes to suggest changes to S1000D and MIL-STD-3031 are explained.

Appendix A An Eagle’s-Eye View of the Entire S1000D Specification. This training can’t provide more than an introduction to S1000D. Appendix A will be a convenient reference for users to go to when they need to find additional information as they tackle new projects.

A PowerPoint Presentation for the ClassroomThe PowerPoint presentation that accompanies this guide is designed for a classroom introduction to the use of S1000D in the Army. The slides review the highlights of each of the modules, and include further detail in the notes. The suggested schedule is:

Day 1 Training Overview and Introduction – Modules 1 and 2The Essentials: Understanding the CSDB and the DM structure – Module 3

Day 2 Layered Decisions: the Business Rules – Module 4

Day 3 S1000D and the Acquisition Process – Module 5The Change Process – Module 6

This guide provides you with more detail, as well as some exercises to help prepare the trainees for their first real S1000D assignment.

2

MODULE 2 - INTRODUCTION TO S1000D Definition of S1000DS1000D is an international specification for the acquisition and production of technical publications. It is designed so that it can be customized to support any type of equipment, military or civil, in a way that general purpose standards do not (e.g., Darwin Information Typing Architecture (DITA)). This specification calls for information to be stored in a database, typically in the form of electronic modules. Because S1000D reflects standards that require information to be generated in a neutral format, it can be implemented on many different Information Technology (IT) systems. This combination of flexibility, modularization, and neutrality makes the use of S1000D attractive all over the world.

How S1000D EvolvedS1000D was initially developed by the European Association for Aerospace Industries (called AECMA, from its original French name). AECMA is now the AeroSpace and Defence Industries Association of Europe (called just ASD). The current specification was jointly produced by ASD, the Aerospace Industries Association of America (AIA), and the Air Transport Association of America (ATA). These organizations formed a joint Technical Publications Specification Maintenance Group (TPSMG) to establish and harmonize documentation standards for the participating nations; this function is now performed by the S1000D Steering Committee.

S1000D came about because in the early 1980s, most civil airline projects were being documented in accordance with the ATA 100 specification. However, documentation for military projects in Europe was being produced for a wide variety of national military specifications, with new procedures constantly being introduced. As collaborative (i.e., joint) projects became more frequent, it became obvious that some sort of standardization of the source data was needed. In addition, developments in both Integrated Logistics Support (ILS) and Information Technology (IT) called for an international standard to be defined. Such a standard would also let technical data be shared among the different applications that support various phases of the life cycle. At the same time, both industry and its military customers were beginning to rely on complex computer-based systems to support technical publications.

In response to all this, ASD’s Customer and Product Support Committee established a Documentation Working Group, comprised of European industry representatives, to recommend a unified method for documenting air vehicle projects. They decided to use ATA 100 as a starting point, and involve the participating nations’ military representatives to figure out how to bring in the applicable military (MIL) specifications. The resulting Augmented Documentation Working Group (ADWG) established task groups that harmonized specifications and established commonality wherever they could. Their work made it possible to develop the international common source database proposals that were incorporated into the S1000D publications specification.

In 2000, the North Atlantic Treaty Organization (NATO) produced a technical data roadmap that recommended combining the best features of S1000D, MIL-STD-87269, MIL-HDBK-511, and XML. As a result, the U.S. Services and the U.S.-based AIA got involved in the sustainment of S1000D. The release of S1000D Issue 2.0 satisfied the NATO roadmap objectives. Shortly thereafter, the ATA decided to combine their specification efforts with S1000D.

3

ASD, AIA, and the ATA are now committed to promoting common, interoperable, harmonized international technical publications data maintenance, which includes the joint development and maintenance of S1000D. The steering committe, composed of various international government and industry representatives, is now responsible for maintaining S1000D. IT specialists in an Electronic Publications Working Group (EPWG) support the steering committee by helping them keep up with the rapid development of technology. The steering committee is also working with Advanced Distributed Learning (ADL) to ensure that training data in a CSDB is structured in a way that meets the requirements of the Shareable Content Object Reference Model (SCORM), so it can be used for interactive training. NOTE: The use of S1000D for training content is not addressed by the business rules in MIL-STD-3031. Any program that desires to produce training content with S1000D should coordinate their plans with TRADOC.

S1000D and the ArmyThe Army has been involved with the development and sustainment of S1000D (through the Land Working Group (WG) and the United States S1000D Management Group (USSMG)) since 2006. An extensive analysis of S1000D was conducted to determine if it could satisfy the Army's requirements for technical data to operate and maintain equipment. The analysis found considerable capability with S1000D, but it also identified some functional gaps. The Army sponsored a number of S1000D change proposals that were incorporated into Issue 4.0 to ensure that S1000D satisfies a majority of Army requirements.

Because S1000D is a standard designed to be tailored for the needs of different users, specific Army business rules were needed. Those necessary Army business rules were published in 2009 as MIL-STD-3031.

S1000D and MIL-STD-40051 are both approved and acceptable technical data standards available for use in the Army. Any Army program developing S1000D data must also be in compliance with the business rules defined in MIL-STD-3031.

Figure 1. The Army's place in the S1000D management structure

New TerminologyIn some cases, S1000D uses terms for concepts with which you are probably already familiar. It is important to become familiar with the new words because S1000D, MIL-STD-3031, and related documents use them almost exclusively. The following table lists these new terms along with the comparable Army term you are probably more familiar with and its definition.

4

S1000D Term Army Term Definition

applicability effectivity

The state or condition when associated data is valid (i.e., applying to a certain configuration, model, or even environmental condition). Applicability may also be used to describe how data modules pertain to different customers for delivery. The term “effectivity” is not used by S1000D.

illustrated parts data

parts list, illustrated parts catalog, or RPSTL

Data modules that contain repair parts and special tools information.

information set Content requirement

Information sets define content requirements. Information set requirements can be collected together to provide an author with content requirements for a subset of data or for an entire publication.

Interactive Electronic Technical Publication (IETP)

Interactive Electronic Technical Manual (IETM)

The interactive presentation of data modules that are displayed on-screen and are not page formatted.

product materiel or end item

The equipment or materiel that is the primary subject of the technical data. This is used in lieu of terms like “aircraft,” “vehicle,” or “ship” since S1000D can apply to air, land, or sea products.

first verification and second verification

validation and verification

The terms first and second verification are used in S1000D and have the same corresponding meanings as validation and verification, respectively.

publicationTechnical Manual (TM) or IETM

A publication refers to the presentation of data modules regardless of its output format (e.g., screen or paper).

reset area guidepostThe reset area is a part of the IETP viewing area that contains access to functionality such as the ability to return the IETP view back to its default settings.

The Modular Approach In the past, authors often reused parts of other documents when the procedures or equipment described were the same. Until the advent of the computer, this borrowing was difficult to track and control. A modular approach that stores coded chunks of texts or illustrations in a technical information repository is far more efficient and easier to use. Under S1000D, all data modules that are applicable to a given document (or “product”) are gathered and managed in a database, the Common Source DataBase (CSDB). Note that this CSDB can be just a Windows directory structure or a collection of distributed databases – nothing fancy – and it requires no particular software.

5

The "common" in Common Source DataBase does not mean that one common database exists for all S1000D data nor does one common database exist for all S1000D data in the Army. It means that a common (or standard) database exists for a project's S1000D data. And, even at a project level, the CSDB may be distributed among multiple contractors. A common source database is not a content management system but rather a set of tools for managing the source data.

An individual data module may be used more than once in the output document, but it is never duplicated in the CSDB. The module is just pulled and used whenever it is needed. This ensures that only one version of a procedure or figure will appear in a document. It also means that information is easier (and cheaper) to keep up-to-date—any change can be reflected everywhere that module is used. (The module’s identifier (data module code) makes sure that it will not be confused with an older version. New documents using that information can have the latest and best (“optimized”) version, but they can also specify an older one (if their equipment configuration calls for it.)

Because data modules can be reused in contexts independent of their original purpose, each data module includes its own distribution, handling, security, and related metadata.

As the figure below shows, reuse can take place in the course of putting a document together or after the CSDB has been delivered.

Figure 2 Data Module Reuse

This means, however, that a new document must be written in such a way that its components can be stored in a database and used by others as needed. S1000D is the tool for ensuring the product being developed (by authors) or the product being contracted for (by acquisition professionals) can become useful (and “reusable”) data modules in the database. This combination of standardization and flexibility can improve the accuracy and consistency of the data—once authors are familiar with S1000D.

6

Data Modules: The CSDB Building BlocksInformation produced in accordance with S1000D is in a modular form. A Data Module is defined as “the smallest self-contained information unit within a technical publication.” It is similar to a single procedure or single topic Army work package.

The data module has two parts as follows:

1. An identification and status section that contains all the information (metadata) needed to manage the module and the data contained in it, such as the data module code, originator, issue date, security classification, and applicability. The Data Module Code (DMC) identifies the equipment (including specification of the specific applicable assembly or component) and an Information Code (IC) that identifies the particular activity. Each DMC is unique.

2. A content section that varies with the type of data module. The three basic kinds of data modules are: one for defining publication content, one for providing support information, and one for administrative use. (All use XML schemas and tags.) The data module types in S1000D Issue 4.0 are:

Content: Descriptive Procedural Crew Fault Maintenance planning Illustrated parts data Process Wiring data Wiring description Maintenance checklists Training and Learning (used only with the coordination and support of TRADOC)*

Data management: Technical information repository (used with restrictions in the Army) Container Applicability cross-reference tables

Administrative: BREX Data module list Data dispatch notes Comment

*Note: The Army has not adopted S1000D for use with training content and no business rules in MIL-STD-3031 address training requirements.

As Figure 2 shows, data modules may be reused in multiple places, as applicable, within a publication. For example, a procedure might appear in conjunction with several different pieces of equipment within a system. When the document is being planned, the following process would occur:

a. the appropriate information set (or sets) is selected (from MIL-STD-3031);

7

b. a list of the data modules that are required (or already exist) to meet the scope of that set is then prepared; and

c. a publication module is used to list all the modules in the order in which they will appear. A single data module may be referenced in a publication module as many times as needed.

The stored modules may be used in two possible ways. In the first, the modules are imported into a document that the end user will see on a screen or within a paper copy. In the second approach, the Interactive Electronic Technical Publication (IETP is the S1000D term; it is equivalent to an Army Interactive Electronic Technical Manual (IETM)) links to each desired module so the end user can see the data modules on a viewer or browser. An IETP may consist of local copies of the data modules from a CSDB (for disconnected users) or to a central CSDB (in a connected environment) that is accessed by multiple users.

The goal of S1000D is to eventually permit data modules to be used not only by other documents, but by other projects as well. While the mechanism is not yet in place in the Army, ultimately other projects should be able to locate existing useful data modules and arrange to incorporate them into planned documents.

More on data modules will be presented in Module 3. Trainees should be aware that although some legacy S1000D documents used Standard Generalized Markup Language (SGML), only XML is supported by the schemas for S1000D Issue 4.0 documents.

Why Programs Are Choosing S1000D and Why the Army is Implementing S1000D Policies to Support ThemThe original European ADWG believed that S1000D would have the following benefits:

Reduced cost of information generation—cuts down duplication of effort Increased economical support planning Reduced cost of deliverable publications Increased uniformity of standards for all participants in a project Improved standard format for data exchange to be exploited by future projects Enhanced interoperability (especially useful in a joint-services environment) Improved clarity and cheaper translation (if the recommended ASD Simplified Technical English

(ASD-STE100) is used)

Other advantages of using S1000D are as follows: It is structured so as to make tailoring more explicit, so that all sorts of equipment can be

supported within a common approach It is designed to allow neutral management and delivery of uniform base data, with output

form to be chosen by the user Information and output can be transferred among disparate IT systems Information maintenance costs are lower due to the reduced volume of data It is designed for integration with other international data standards, such as those defining

Logistic Support Analysis Record (LSAR) Subsets of information can be generated to meet specific user needs The data module concept can be applied to legacy data, which is particularly appropriate for a

legacy work-package environment such as the Army

8

A well established technical support community cooperates to resolve the requirements needs of the S1000D user community

Some Army programs have chosen S1000D to better position themselves for the future. In addition to the reasons above (especially customization and interoperability), programs cite foreign military sales as a reason to use S1000D. The Joint Services have already defined business rules for use with S1000D.

The Navy has developed Department of Navy as well as Systems Command (SYSCOM) level business rules. The Naval Air Systems Command (NAVAIR) and Naval Sea Systems Command (NAVSEA) have issued policy letters indicating that S1000D is suitable for use.

The United States Air Force (USAF) has several programs fielded using S1000D, and they are developing service-level business rules.

The US Coast Guard has developed business rules and a service–wide Standard Numbering System (SNS) database.

Tailoring, through Army-specific S1000D business rules (i.e., MIL-STD-3031), enables interested programs to implement S1000D effectively while successfully meeting all Army and Joint Services requirements. However, these business rules and S1000D-based standards must also be specified in contracts for these programs. Related policies are needed as well. Complementary standards include the definition of the interface with logistics support analysis (GEIA-STD-0007) and LSARs. Mapping is currently being defined for Product Life Cycle Support (PLCS).

Because S1000D was not designed to meet the U.S. Army’s specific requirements, the Army has had to do the tailoring that will make sure that all its needs can be accommodated. It has created Army-specific information sets to describe the desired content of various manuals, as well as Information Code Variants (ICVs) for coding data modules. The ICVs are part of a Joint Services Information Code list. The Army has also created a military standard (MIL-STD-3031) containing Joint Services and Army-wide business rules that address many of the possible decision points in S1000D (more on those in Module 4). It has also modified appropriate policies to accommodate the use of S1000D.

Nonetheless, the use of S1000D for technical publications on Army contracts is still optional rather than mandated.

A fairly wide variety of commercial and public domain tools can now be obtained for supporting S1000D. Among them are:

CSDB management tools Input/output tools Conversion tools Business rule development tools Editors and editing tools BREX checkers Style sheets Publishing tools Viewers

The Main Changes with S1000DThis module has already discussed most of the ways in which S1000D differs from other specifications:

9

The deliverable document contents will be in the form of data modules selected from a set of Army-tailored content selection matrices, with all the information authored in XML.

All project partners store the data modules in a CSDB of some kind. All stakeholders must agree to a set of business rules, implemented at a number of levels, which

specify almost all possible decisions about the document and its contents. Information sets with corresponding information codes define content.

One more difference is particularly germane to the acquisition process:

S1000D requires a more defined-collaborative process between the Government and contractors. All stakeholders work together to complete the content selection matrices, the functionality matrix, and the project business rules. Differences specific to the writing process are as follows:

The sequence of a document’s parts is independent of the content—the publication and process modules take care of presentation and production. Authors focus on content alone.

Authors should write content with data module reuse in mind (i.e., data module content should not be dependent on the context of potentially adjacent data modules).

Data modules (to a large degree) take the place of work packages. However, data modules generally contain a single procedure whereas work packages frequently contain a series of related procedures.

This guide introduces each of these differences in turn: The database and data modules are described in Module 3. Business rules and their importance are discussed in Module 4. The acquisition-related differences are presented in Module 5. Appendix A covers all the topics included in Issue 4.0 of S1000D, so that when the trainees come

to use the full specification, it will seem at least somewhat familiar. (The section below will make the first introductions.)

A few other things people need to keep in mind when they start using S1000D are as follows: Tailoring for a particular project. S1000D was purposely written so it could be applied to many

different types of products. Tailoring is always needed to make it appropriate for a given project. Things like the schemas cannot change; but others, like the requirements for optional elements, how they are to be populated, and the use of specific values will vary with the project. This tailoring is usually done by both the project staff and the chosen contractor, working together, and is documented in the project’s business rules. The project’s contractual documentation needs to specify all these agreed-on project-specific rules. Also, S1000D uses specific conventions to ensure common understanding and to minimize duplication. (For instance, it defines which schema elements are mandatory.) Some conventions have been left for projects to decide; however, conventions like defining the information codes and specifying usage and terminology (e.g., using “name” rather than “designation”) are determined by MIL-STD-3031. Each project needs to document its chosen conventions within its tailored business rules.

Requesting a Change to S1000D. Any amendment to S1000D could affect military and industrial users all over the world, so international agreement is required for any proposed changes that are beyond the tailoring that is allowed. The S1000D Steering Committee considers change proposals at each of their meetings. If the group ratifies them, the Committee will include them

10

in the next version of S1000D. (Issue 4.0 reflects more than 100 change proposals submitted between 2004 and 2008.) S1000D includes instructions for submission of Change Proposal Forms (CPFs), but Army projects’ suggestions for improvements need to follow the process described in Army/Land WG CPF Review Process. LOGSA will assist projects with getting their concepts reviewed by the Land WG and in documenting the approved ones for formal submission. (See Module 6)

Army processes that are affected by using S1000D. Army policies and procedures related to writing or acquiring technical manuals still apply when S1000D is used. The business rules are more critical and more formal with S1000D. And then new processes are developed, like the CPF process mentioned above. Some of these changes are highlighted above; more detail can be found in the remaining modules, especially Modules 5.

Using the Full Specification When It’s NeededAs noted earlier, S1000D is designed to cover technical publication activities in support of any platform, system, or equipment project (air, sea, or land vehicle; equipment; or facilities, civil or military). It describes all aspects of technical publication from information generation, exchange, and management within the CSDB to publication generation and the commenting. The table below provides an introduction to S1000D’s scope. Note that in some areas, the Army has come up with tailored replacements for the information and guidelines that appear in S1000D.

Table I. S1000D Structure OverviewChapter Topic Contents

1 Introduction to the specification

General information: scope of S1000D, how to use it, how to tailor it, and requested changes to S1000D.

2 Documentation process

Overview of the documentation process, including its relation to other processes and specifications such as ASD S2000M and Product Life Cycle Support (PLCS) (ISO 10303 AP239). A process diagram refers to the corresponding chapters.

3 Information generation

General rules for writing for technical publications that are produced on the basis of data modules and CSDB concepts (mostly for authors and illustrators). (A publication is defined as a user’s view of information compiled and published for a customer. It may be an IETP or a page-based publication compiled from data modules or a publication with legacy data.) Chapter sections are:3.2: Basic structure of the data modules.3.3: Use of the information sets that establish the required information scope

and the data module coding strategy. (An information set is an author’s view of the information required, of defined scope and depth, for a data module that will be managed in the CSDB.) Note: The Army will use its own information sets, not those in S1000D.

3.4: Rules for zoning and access.3.5: Updating data modules. 3.6: Rules for the protective marking of data modules (e.g., which element

reflects security classification). 3.7: Details of the quality assurance procedures used during

module/publication development and updated to ensure that the contents are adequate and technically accurate.

3.8: Rules for modular disassembly/breakdown of equipments.3.9: Structural rules for data module production, together with authoring

11

Chapter Topic Contents

rules for writing, illustrations, and multimedia (including components like front matter, warnings, and notes). This section is 1000 pages of useful information for authors.

4 Information management

Oriented towards managing data for publication, this chapter covers the data module structure, rules for interchange of data modules, and rules for updating of data modules so that common technical documentation can be produced. Sections are:4.2: Addressing, storing, and handling of information objects such as data

modules, illustrations and multimedia, and publications, including the information needed to establish a CSDB.

4.3: Details about the coding of data modules. 4.4: Data modules’ associated illustration and multimedia information

(information control numbers). 4.5: Data Module Lists (DMLs) used for managing CSDB content. 4.6: Handling comments on data modules and publications. 4.7: Version control. 4.8: Interchange of data modules. 4.9: Using the publication module and SCORM content package module to

define, prepare, and manage publications and learning content generated from data modules.

4.10: The Business Rules EXchange (BREX) mechanism. 4.11: Use of the process data module. 4.12: Master-customized concept for managing a multi-customer

environment. 4.13: Optimizing and reusing data. This concept includes how significant data

within a data module are handled, a mechanism for grouping properties related to different technical information types, and a production-management mechanism for associating modules representing the same data with different product configurations.

4.14: Applicability model. Can support either static text output or a dynamic output filtered for a particular product configuration.

5 Information sets and publications

Presents the common and specific requirements for the information sets and publications necessary to operate and maintain a given product. Supports publication procurement and management as well as authors and illustrators. For the Army, these information sets are entirely superseded by those in MIL-STD-3031.

6 Information presentation/use

Also supports publication procurement and management as well as IT specialists. Includes:6.2: Rules for page-oriented publications.6.3: Rules for IETPs.6.4: Functionality matrix for page-oriented publications as well as non-linear

display of information. For the Army, this functionality matrix is superseded by that in MIL-STD-3031.

7 Information processing

Technical aspects of the schemas, graphics/notations, information interchange, resources, and software requirements. Software-oriented.

8 Standard Numbering Systems,

Describes the common Standard Numbering Systems (SNSs), Information Codes

12

Chapter Topic Contents

Information Codes, and Learn Codes

(ICs), and learning/training codes used in the data module code. 8.2: S1000D set of SNSs for air vehicles, engines and equipment, tactical

missiles, and general land/sea support equipment. 8.3: Examples of each of the above.8.4: ICs for the above. The Army has added to the IC listings, so this material

has been replaced by the listings in MIL-STD-3031. 8.5: Codes related to training and learning.

9 Terms and data dictionary

9.2: Glossary of the terms, abbreviations, and acronyms used.9.3: Definitions of the XML data elements.

More information on S1000D and on ASD publications can be found at http://www.s1000d.org/ and http://www.asd-europe.org/, respectively. MIL-STD-3031 can be found at https://assist.daps.dla.mil/quicksearch/ and https://www.logsa.army.mil/mil40051/S1000D.cfm.

SummaryS1000D is an international specification for the acquisition and production of technical publications. It was developed in Europe to be a common standard for collaborative projects. Some U.S. Army projects want to use this specification, so the Army released business rules and policies ensuring S1000D is successfully applied and that the Army’s requirements are met.

S1000D calls for information to be stored in the form of electronic modules in a common source database. (This database can be a Windows directory structure or anything easily managed; it requires no special hardware or software.) Each data module may be pulled and used as many times as needed in the output product.

Each data module has an identification and status section that contains all the information needed to manage the module and the data within it. Each data module also contains a content section that varies with the type of module. Business rules (S1000D, Army, and project-specific) govern the structure and the use of the various modules; they are one of the most important aspects of writing to S1000D. The ultimate output is in a neutral format that allows the data to be used on a wide variety of systems, which is one of the main advantages of S1000D.

The main differences people will see in working with S1000D are the modular format and common source database; the use of business rules that are tailored to govern all the project-related decisions; Army-specific information sets and codes; and the use of a standardized, detailed, Army-specific functionality matrix to specify the document requirements. All of these provide advantages to the Army.

The level of tailoring expressed in the business rules may be a change for many users, but S1000D is designed to be customized.

13

MODULE 3 - THE ESSENTIALS: DMs and Other CSDB ObjectsThe concept underlying all of S1000D is that information for a publication is stored in individual units (called data modules) in a database, so that they can be efficiently used, reused, and modified if necessary. This training module provides an overview of the database, the structure of the data modules, the types of modules, and the DMC that makes it possible to access and manage the individual modules.

The Common Source DataBase (CSDB) and How It WorksThe CSDB is the glue that holds the modular information management system together. It stores all the information objects used to produce a project’s technical publications. (Note that the logic and presentation engines are separate from the CSDB.)

Figure 3. CSDB, Logic Engine, and Viewer

A good CSDB management tool should meet five objectives: Support the technical publication process through easy access and reuse Support controlled authoring Support quality assurance Support the exchange of data among partners, suppliers, and customers Support the delivery of technical publications in various formats on various media.

S1000D specifies the data structure of the information objects and the processes for a CSDB management tool. The choice of software for implementing it is not specified; the database could be as simple as a Windows directory structure or as complex as a collection of distributed databases. The metadata for any CSDB needs to be accessible so all project participants can look for reusable information (data modules) in the CSDB.

14

Presentation Engine

Logic Engine

CSDBCSDB

The CSDB ObjectsSix different kinds of information objects are stored in the CSDB. The types are as follows:

Data modules Illustrations and multimedia Data module lists Comments Publication modules (and SCORM modules) Data dispatch notes

For this LOGSA-related training, the data modules are the major focus. The next section describes the data module in greater detail as this is the primary type of information objects stored in the CSDB. The remaining five information objects contained in the CSDB are described briefly below. (S1000D itself provides far more detail for all of them.) Except for the illustrations, schemas exist for each of these objects:

Illustrations and multimedia associated with a data module. These are the figures, videos, animations, 3-D objects, or audio files that can accompany and supplement the contents of a data module (see Content in the next section). (S1000D Chapter 3.9.2)

Data module lists. Two lists are used for planning, managing, and controlling the contents of the CSDB for individual projects:

The Data Module Requirement List (DMRL) identifies all the modules required for a project. The DMRL should be part of the Technical Manual Contract Package (TMCP).

The CSDB Status List (CSL) is a convenient status reference; it is readily compared with the DMRL to assess how far along the effort has progressed; and when various agencies or companies are contributing to the same CSDB, they can verify who is working on what. (S1000D Chapter 4.5)

Comments. Comments are a way for users to report on errors or to suggest improvements to a data module. These can be used either during the verification process or when the modules are in service. Comments are made using XML markup (which for an IETP can generate a DA Form 2028, if the project chooses) that is sent to whoever provided the information. (The same markup is used to respond, so the history can be tracked.) The use of the comments data module is not required by either S1000D or MIL-STD-3031. Projects may choose to use the traditional DA Form 2028. (S1000D Chapter 4.6)

Publication module. This module is used to manage both the preparation and publication of an S1000D document. It has an identifier (the Publication Module Code (PMC)), a status section, and a content section. A publication module lists every one of the data modules (and any other appropriate publication modules or external legacy PDF publications) in the exact order in which the publication will deliver them to the user.

Data dispatch notes (DDNs). A DDN describes the contents of a delivery package (e.g., change package). It lists all items (data modules, publication modules, illustrations, etc.) included in a particular data delivery. (S1000D Chapter 7.5)

15

The Data ModuleThe data modules in the CSDB are the basic information units for a document. Each one contains a particular topic or procedure related to the equipment. Data modules contain text as well as references to any illustrations, multimedia objects, or other data that are related to that text. (The illustrations and multimedia objects are not stored in the data module itself, but rather referenced as with an HTML page.) They thus provide a publication’s contents. Data modules have defined neutral (non-proprietary) structures.

As noted earlier, each module in a project CSDB is unique. If the same text or graphic is repeated within a document or another publication on that project, that module can be reused as many times as needed. This means that information that is likely to repeat should be in its own module (as long as it is a complete set of information, e.g., a repair procedure, and is completely self-contained). Then in the publication, it can be combined with other modules containing new information.

A goal of S1000D is to eventually permit data modules to be used by other projects and even other services since a data module may be appropriate for more than one program.

All data modules use the same basic two-section structure. The first section contains Identification and Status information, and the second section contains the actual content that is presented to the user. The content of a data module is specific to the type of the data module, which is written in accordance with that type’s schema.

Identification and status contains all the information needed to manage a module and the data contained in it—the metadata.

The identification segment contains identification and address information. The identification portion, which is unique, includes the data module code (see the next section for more detail), language, and issue information. The address portion includes the issue date and the data module title.

The status segment contains data such as security classification, responsible partner company and originator, applicability (effectivity), quality assurance status, data restrictions (export control, distribution, etc.), and the reason for any update that was performed.

Together, the two segments make it possible to control a module’s retrieval, to automatically compile sets of information, and to manage quality control; as well as provide applicability and other information to users. Note that the contents of identification and status govern the whole data module, so its applicability, classification, and other requirements must always be appropriate for all of the module’s content; whatever the individual content segment’s applicabilities or classifications may be.

Note too that sometimes the latest update of a piece of information or procedure is not actually the appropriate one for a publication. The issue number in the ID segment allows an author to specify the right issue of a data module for a particular use. Similarly, the language code distinguishes modules that contain the same information, but in different languages.

Content contains the text (and links to the illustrations or multimedia objects) that is presented to the user. The structure and elements of this segment of a data module are dictated by the type of data module selected and its schema. The data modules likely to get the most use for Army manuals are Descriptive, Procedural, Crew, Illustrated Parts Data, Fault, Maintenance Checklists, and Publication.

16

The content selection matrix dictates the type of content that is required by a project. The maintenance plan and the complexity of the equipment itself will dictate the level of detail required in each data module. Information Codes (ICs) must be identified that match the contents of each data module (in most cases the content selection matrices dictate the IC that must be used).

Further details appear in Chapter 3.9 of S1000D. All the module types are briefly described below just to give the big picture.

Types of Data ModulesThe three basic categories of content data modules are as follows: those that define content for a technical publication, those that provide supporting information, and those that are designed to assist in project management. (The content modules are defined in the content selection matrices of the Army’s business rules.) Associated with each type is a well-defined schema for capturing, structuring, and representing the appropriate information.

Common entities, elements, and attributes (described in Chapter 3.9.5.2.1 of S1000D) are used in defining all of them. The data module types are:

Content: Descriptive. Used for descriptive information. This includes content like General

Information, Theory of Operation, some Supporting Information (e.g., Components of End Items (COEI), Basic Issue Items (BII)), and Army wiring diagrams. No procedural steps are in the descriptive schema. (Chapter 3.9.5.2.2)

Procedural. Used for procedural (task and steps) information. The level of detail in this type of data module is dictated by the equipment breakdown (reflected in the SNS) and the maintenance plan (reflected in the ICs selected). (Chapter 3.9.5.2.3)

Fault. Used for fault reporting, isolation, and correlation information (troubleshooting). (Chapter 3.9.5.2.4)

Maintenance planning. Used for maintenance planning information. For Army purposes, this is limited to the Maintenance Allocation Chart (MAC). (Chapter 3.9.5.2.5)

Crew. Used for information to be used by crew or operators of the equipment. (Chapter 3.9.5.2.6)

Illustrated parts data. Used for parts lists and illustrated parts data. The module’s elements include references, figure information, catalogue sequence number information, and initial provisioning project information. (Chapter 3.9.5.2.7)

Process. Used in an IETP for sequencing other data modules or steps, using dynamic state table information as well as input from the user or equipment, so that the user receives a seamless, logical flow of information. This module is useful for diagnostics. A logic engine processes the interactive structures within the process data module and determines the presentation of information. (Chapter 3.9.5.2.10)

Learn. Used for training-related material. (Chapter 3.9.5.2.13; also see Chapter 4.9.5) Maintenance checklists. Used for capturing lists for preventive maintenance, services, and

inspections. (Chapter 3.9.5.2.14)

17

Data management and project: Business Rules EXchange (BREX). Used for sharing all the business rules applicable to a

publication among the parties involved in its production. (Chapter 4.10) DM Lists. Used to identify the data modules required for a project (DMRL) and the status

of data modules in the production process (CSL). (Chapter 4.5) Technical information repository. Used to manage data external to and referenced by a

data module (like circuit breakers, parts information, zones, access, organizations, or support equipment). (Chapter 3.9.5.2.11)

Not required Cannot be part of delivered data intended for maintainer/operator use Can be used for internal authoring environment

Container. Used for associating several alternate data modules representing the different versions of the same data. (Chapter 3.9.5.2.12)

Cross-reference tables. Used to manage the applicability of data modules based on equipment attributes or conditions. (Chapter 3.9.5.3)

Comment. Used to report errors and recommend improvements in the technical data. (Chapter 4.6)

Data Dispatch Notes (DDNs). Used to list the items included in a delivery of data, like a manifest.

Figure 4. Data module types and information codes

Authors will become very familiar with Chapter 3.9. Also, data modules may need to be updated or revised for a variety of reasons. The process is described in the summary of Chapter 3.5 that appears in Module 6 of this guide.

18

PLEASE NOTE that the Army does not provide business rules or other guidance for using the following two types of content modules because it is anticipated that they will not be used by Army programs. Any project that believes it needs to use the wiring schema should consult with LOGSA.

Wiring data. Used for data and specifications on wires, harnesses, electrical equipment, and standard parts. Generally in tabular format which is currently supported by the descriptive schema. Not currently used by the Army. (Chapter 3.9.5.2.9)

Wiring description. Used for information about the wiring, such as access, layout, and maintenance requirements. Not currently used by the Army. (Chapter 3.9.5.2.9.13)

Use of XML and SchemasEach type of information object has a corresponding schema in Issue 4.0 of S1000D:

Table II. Data Modules and Schemas

DATA MODULES SCHEMAS

Descriptive descript.xsdProcedural proced.xsdIPD ipd.xsdFault fault.xsdLearning learning.xsdMaintenance Planning schedul.xsdMaintenance Checklists and Inspections checklist.xsdCrew crew.xsdProcess process.xsdTraining scormcontentpackage.xsdContainer container.xsdApplicability Cross-reference appliccrossreftablea.xsdConditional Cross-reference condcrossreftable.xsdProduct Cross-reference prdcrossreftable.xsdTechnical Repository techrep.xsdBusiness Rules EXchange (BREX) brex.xsdWiring Description wrngflds.xsdWiring Data wrngdata.xsd

OTHER INFORMATION OBJECTS SCHEMAS(illustrations and multimedia objects)Publication Module pm.xsdComment comment.xsdData Dispatch Note (DDN) ddn.xsdData Module Lists (DML) dml.xsd

19

The Data Module Code (DMC)Each data module has a unique and complex identifier. The DMC is used to manage data modules in the CSDB, retrieve them, or access them in an electronic environment. The DMC, together with the metadata in the identification and status section described above, allows the chunks of information to be independently managed and reused. The illustrations or multimedia objects associated with the data modules have a similar code.

The DMC’s structure is standardized, even though the lengths of its individual components may vary. (The DMC can be anywhere from 17 to 41 alphanumeric characters.) As shown in the table below, it is partitioned into three parts: “hardware identification,” “information type,” and “learn type.” The learn type information applies to Human Performance Technology (HPT) or training data modules and is optional.

Table III. DMC Breakdown

SEGMENT BREAKDOWN LENGTH

Hardware identification

Model identification code 2 to 14 alphanumeric charactersSystem difference code (SDC) 1 to 4 alphanumeric charactersStandard numbering system (SNS) 6 or 8 alphanumeric characters*

System 2 alphanumeric charactersSubsystem 1 alphanumeric characterSub-subsystem 1 alphanumeric characterUnit or assembly 2 or 4 alphanumeric characters

* There may be an additional optional Material Item Category Code (MICC) character as the first character

Disassembly code (DC) 2 alphanumeric charactersDisassembly code variant (DCV) 1 to 3 alphanumeric characters (no hyphen before)

Information type

Information code (IC) 3 alphanumeric charactersInformation code variant (ICV) 1 alphanumeric character (no hyphen before)Item location code (ILC) 1 alphanumeric character

Except as noted, the characters for the elements are separated by hyphens, so the result is:

(minimum) YY - Y - YY-YY-YY - YYY - YYYY - Y

(maximum) YYYYYYYYYYYYYY - YYYY - YYY-YY-YYYY - YYYYY - YYYY - Y

The unique Model Identification Code is very important, because it is the point of reference in each data module. The project may decide to allow the use of more than one Model Identification Code on a project - allowing the use of existing data without change or recoding.

Chapter 4.3 of S1000D explains each of the DMC segments in detail and how the codes are applied. (Figure 1 in Chapter 4.3.9 provides a handy segment breakout with some examples and alternatives.) In summary, the primary sections of the DMC are as follows:

20

Model identification – This identifies the equipment that the data module applies to. Model Identification (MI) codes are selected by the project. To ensure universally unique data module code, the MI must be registered and approved by the North Atlantic Treaty Organization (NATO) Maintenance and Supply Agency (NAMSA) (http://www.namsa.nato.int/s2000m/s2000m_moi14_e.htm). There is a process for registering Model Identification codes.

o Send an e-mail containing the code(s) needed and a brief description for each and the product code(s) it will be used for and the contact information (including name, title, telephone number, FAX number, address and e-mail) requesting registration to spec2000m@namsa.nato.int.

o Once registration confirmation is received, notify LOGSA via email and identify the registered codes.

System difference code – This is used to indicate when an alternate version or configuration of the model applies to the data module.

Standard Numbering System – This number indicates the system, subsystem, sub-subsystem, and unit or assembly which applies to the data module. The Army equipment SNSs are based on the same equipment breakdown used for parts and MAC data.

Disassembly code + Variant – This indicates if the procedure in the data module is applicable to a particular state of disassembly of the component.

Information code + Variant – This describes the topic or procedure of the data module.

Item location code – This describes the location of the component that is the subject of the data module if it is significant to the content. For example, a different procedure may be relevant if the assembly is on the equipment, removed from the equipment, or on a shop stand.

Learn code – This is an optional code that is applied only to training data modules.

Figure 5. Data Module Code Breakout

The S1000D Steering Committee maintains seven SNS structures that codify the functional or physical breakdown of an item or product—for example, ordnance or surface vehicles. A project can modify these SNSs to suit its needs or may even choose to create its own SNS. A generic SNS is provided and includes numbering for presenting information on everything from dimensions to transporting to maintenance to crew information.

21

Publication Modules CodesA publication module is a "wrapper" that sequences all of the content (data modules and nested publication modules) of a page-oriented or interactive electronic publication.

The PMC’s structure is standardized, even though the lengths of its individual components may vary. (The PMC can be anywhere from 14 to 26 alphanumeric characters.) As shown in the table below, it is partitioned into four parts: “Model Identification code", "Issuing Authority", "Publication number", and "Volume number".

Table IV. PMC Breakdown

SEGMENT BREAKDOWN LENGTH Sample

Model Identification code 2 to 14 alphanumeric characters ROLLERIssuing Authority

Issuing Authority/Service/Command 1 alphanumeric character 5Category (FSC/SSCC) 1 alphanumeric character (no hyphen before) 3895

Publication numberType of Pub (Pub Identifier)/Maint. Level 3 alphanumeric characters MM2Sequence number 2 alphanumeric characters (no hyphen before) 01

Volume number 2 alphanumeric characters 00

The MI code is the same as the DMC. The Issuing Authority codes are listed in the table below. Additionally, the FSC can be obtained from https://www.drms.dla.mil/asset/fsclist.html. The publication number is a three digit joint service publication code and a two digit sequence number which is project assigned. The three digit joint service publication code for those publications typically used by the Army are listed in MIL-STD-3031. The volume consists of a two digit volume number and is "00" by default.

By using the above breakdown explanation, for TM 5-3895-379-23, the S1000D PMC would be ROLLER-53895- MM201-00.

MM2=Field Maintenance Manual (-23)

Table V. Issuing Authority CodesCODE PROPONENT

0 Tank-automotive and Armaments Command (TACOM

1 Army Materiel Command (AMC)

2 Aviation and Missile Command (AMCOM)

3 Armament Research, Development, and Engineering Center (ARDEC)

4 Communications-Electronics/Life Cycle Management Command (C-E LCMC)

5 CECOM Communications Security Logistics Activity (CSLA)

6 Integrated Logistics Support Center-Soldier Biological Chemical (ILSC-SBC)

7 Research, Development, and Engineering Command, Edgewood Chemical Biological Center (ECBC)

8 Joint Munitions Command (JMC)

22

CODE PROPONENT

9 Reserved

A Reserved

A PMC can be a parent PMC or it can be a nested PMC. The only difference between the two is that with a nested PMC, the entire 5-digit publication number is assigned by the project (as opposed to just the final 2 digits, and the volume number is also assigned by the project.

A Closer Look:Standard Numbering System (SNS)The SNS consists of four segments: system, subsystem, sub-subsystem, and unit/assembly. These segments identify the equipment breakdown. The SNS is used in the same way as a Functional Group Code (FGC) in that it identifies a particular system, subsystem, component/assembly, or part of the system or equipment.

Functional Group Codes (FGCs)

An FGC is used for development of Maintenance Allocation Charts (MACs), narrative technical manuals, and Parts Lists.

A standardized method of FGC assignment for commodity types of components/items is normally established by the requiring authority (e.g., technical publications community). These standardized assignments make it easier for the user in the field to cross-reference between different TMs of equipment maintained by that organization. For instance, engines may always be documented under an FGC of "04" across all Army helicopter types.

The FGC sequence of the MAC will dictate the sequence of entries in the narrative technical manual and Illustrated Parts Data (IPD). A basic (usually two-position) group code is assigned to identify major components, assemblies, and subassemblies to a functional system. Subordinate sub-functional groups/subassemblies are coded to relate back to the basic (top position) FGC in a sequential, next higher assembly (NHA) relationship (i.e., top-down breakdown structure).

Mapping FGC to SNS

The maximum length of an FGC is 11 characters, whereas an SNS is six or eight characters (not including a MICC). By converting the second and third level subassemblies (the 3rd & 4th and 5th & 6th positions in an FGC) to single character codes (subsystem and sub-subsystem in an SNS), a 10-character FGC can be mapped to an 8-character SNS.

For example, FGC 0102010100 (10 characters) SNS 01-CB-0100 (8 characters)

This reuse of an FGC allows for easy population of an SNS, leaving both the system and unit/assembly codes unchanged between FGC and SNS.

23

Figure 6. FGC to SNS Conversion Chart

24

A Closer Look:Information Codes and Information NamesSeveral codes provide metadata to identify the contents of a data module. The model identification code identifies the equipment to which the data module applies, the SNS identifies the system, subsystem, or component (of the model) to which the data module applies, and the information code identifies the topic or procedure that is provided by the data module.

For example, a data module containing the information code 720A will always be an Install Procedure. The code 720 is the information code, A is the variant (in the case of “A,” it is the base information code and not a variant), and Install Procedure is the information name. An information name is the human readable version (or short definition) of the information code. The information name along with the equipment component name or technical name (determined by the SNS) will form the data module title (e.g., “Fuel Valve FV4P – Install procedure”).

S1000D Chapter 8.4 provides the list of information codes and their corresponding suggested information names. Only the A variants are provided by S1000D, all other variants are determined by projects or organizations. In the case of the Army, all information code variants and information names were determined at the Joint Service level so that there is common understanding of information codes across all US Services to maximize data module reuse. The list of Joint Service Information Codes (JS ICs) is provided in MIL-STD-3031 Appendix B.

When determining the information names for the JS IC list, several factors had to be considered:

What is the recommended name provided by S1000D?

What is the legacy name used for the subject in traditional Army publications?

What are the legacy names used for the subject in the traditional publications of the other services?

Priority was given to the S1000D-recommended names so that U.S. data modules can be as universally accepted (and reused) as possible. Effort was made to use U.S. Service (including Army) names where it was deemed important. With few exceptions, if an information name other than the S1000D recommended name was needed, a variant other than “A” was assigned in the JSIC list. The variant A information names were only changed if the titles only differed by word construct (e.g., “Installation procedure” vs. “Install procedure”).

Every effort was made to ensure that the meaning of the information name matches the meaning of the legacy content requirement – even though the words may be slightly different. For example, the information code 131M has an information name of “Normal operation check – Preflight” which corresponds to the legacy content title of “Preflight check.”

25

SummaryThe CSDB stores all the information objects used to produce a project’s technical publications. S1000D specifies only the data structure for the CSDB; the database can be as simple as a Windows directory structure or as complex as a collection of distributed databases. Storage of information in separate, readily accessed modules makes the creation of further documents related to a particular product far more efficient.

Six kinds of information objects are stored in the CSDB: data modules, illustrations or multimedia objects associated with a data module, data module lists, comments, publication modules, and data dispatch notes. The data modules are the basic information units for a document. They consist of self-contained text plus references to any data that are related to that text, so they provide all of a publication’s content. A data module can be reused as many times as needed.

Data modules have defined, neutral structures. The first of their two sections contains all the identification and status information needed to manage the module and the data contained in it. This includes controlling its retrieval, automatically compiling sets of information, managing quality control, and providing applicability and other information to users.

The second section is the actual content, which contains the text and links to the illustrations and multimedia available to the user. The two basic kinds of data modules are those that define allowed content for technical publications and those that provide data management. Within each, a number of types of data modules exist. For each type, S1000D defines a schema for capturing, structuring, and representing the appropriate information. XML is used to specify the markup elements that make it possible to identify the information in the data modules.

The DMC is used to manage, retrieve, or access data modules. The DMC and identification and status information together allow the chunks of information to be independently managed and reused. The DMC’s structure is standardized, but the lengths of certain components may vary. (The whole structure can be up to 41 characters long.) It has three main parts: “hardware identification,” “information type,” and the optional “learn type.” The unique Module Identification Code is crucial for managing a project’s data.

SNSs and ICs are used to determine the appropriate level of detail for a module’s content. S1000D includes seven SNSs codifying the functional or physical breakdown of an item or product. These may be modified, or even replaced, by project-specific choices.

A BREX verifies compliance with true/false decisions and provides another method of documenting machine-verifiable decisions.

26

EXERCISE OPPORTUNITIESExercise 1 – Build a Data Module Code (DMC)

Imagine you are part of the OH-58 Kiowa helicopter technical data project team. You will need to have S1000D and MIL-STD-3031 available to complete this exercise. The following model identification codes have been registered with NAMSA:

a. OH-58 Kiowa helicopter (OH58KIOWA)b. Mast mounted sight thermal imaging system (MMSTIS05)c. Rolls Royce engine (RR00XYZ)d. Air-to-air Stinger missile system (ATAS02)e. 50-caliber machine gun (50CALMG)

You have been instructed to develop a data module that provides the instructions for mounting the 50-caliber machine gun to the skids of the airframe. The OH-58 is a new airframe and there is only one model with no variants or alternate configurations. The work to mount the gun will be performed on the airframe itself. The SNS for the gun mounting bracket on the skid is 01-DF-0001. The project has business rules that limit the System Difference Code (SDC) to 1 character and the Disassembly Code Variant (DVC)

Identify the DMC that you will use for the data module you are preparing.

Exercise 2 – Build a Publication Module Code (PMC)

Imagine you are part of the OH-58 Kiowa helicopter technical data project team. The following model identification codes have been registered with NAMSA: OH-58 Kiowa helicopter (OH58KIOWA)

You have been instructed to develop a PMC to cover the following: Field Maintenance Manual, Crew checklist, and Maintenance test flight manual

The following information is relevant: Proponent for OH-58 is AMCOM FSC: 1520 Initial sequence begins at “01” No previous Publication Module Codes exist

Identify the PMCs that will be developed for each.

27

Exercise 3 – Data Module Structure

Describe the function of the identification and status and the Content portions of the data module.

Exercise 4 – Data Module Types

Of the data module types that define content, which ones do you expect to use most in your work, and why? Are there any you are unlikely to use?

28

Exercise 5 – Information Codes

Connect the information codes below with the data module type most likely to be used to prepare the content.

29

MODULE 4 LAYERED DECISIONS: THE BUSINESS RULESHow Business Rules WorkBusiness rules reflect policies, procedures, or constraints that affect how a project or organization conducts its business. They are implemented wherever a decision point or tailoring opportunity exists.

The business rules that apply to S1000D publications are layered. Each layer inherits and extends the previous layer’s rules. The requirements defined within S1000D as “must” statements are the overarching layer. They essentially make a number of the possible decisions in advance. For each of the layers below that one, the total number of rules (decisions made) increases and the number of possible decisions remaining decreases. The goal is to have all (or virtually all) the decisions made by the time that actual writing begins, so that everyone is writing to the same rules.

Figure 7 Business Rules Layers

S1000D was purposely written to accommodate many different organizations, business processes, and types of products. Not all S1000D’s business rules apply to Army work, and not all Army (or other services) work is covered by the existing rules. For this reason, the Army has written a Department of Defense Standard Practice providing Army business rules for S1000D (MIL-STD-3031) that defines the additional requirements that are applicable to the various rules in S1000D. MIL-STD-3031 also includes the business rules agreed to by the Joint Services. Business rules relating to S1000D and the Army will be of particular concern to acquisitions professionals, since it will be their responsibility to make sure that those business rules appear in the initial Technical Manual Contract Package (TMCP).

In addition to these Army/Joint Services business rules, each project will need to do some tailoring to make sure that the project’s particular needs will be met. These additional project-specific business rules need to be included in the contract documentation (via Data Item Description (DID) DI-TMSS-

30

81784, Army S1000D Project Business Rules) to make sure all parties are in agreement about them. Project managers and their staff will need to draft the initial project-related rules and make sure that business rules for the remaining open decisions are listed as a deliverable in the Contract Data Requirements List (CDRL). Project and contractor staff will then work together to choose the business rules for those decisions. (The authors, of course, need to make sure that their writing complies with all those rules.)

The sections below discuss all three general layers of rules. Note that layers may be within those layers. For example, one LCMC may have rules it wishes to apply to all the programs in its command. More decisions will then already have been made by the time individual projects review their decision points.

S1000D Decision PointsS1000D specifies how things are to be done in many areas. These are mandatory requirements, and the TMCP can refer to S1000D to invoke them. However, S1000D also includes a number of spots that remind projects (or organizations) of decisions that should be made. (Some are quite explicit – they say something like “the project must decide” – while others are “should” statements.) A decision needs to be made for every single one of these items. Some of them are covered by MIL-STD-3031, but many are left up to the project.

A great many of these decision areas involve allowable values or attributes. Others are part of the planning and acquisition process; i.e., decisions regarding the content and publication of the document (these include the content selection matrices and the information sets), the functionality matrix, quality assurance, or requirements related to interfaces with others systems. S1000D business rules can be categorized to make them easier to understand, as with the categories shown in the table below, which shows examples of Army and project decisions given for each area. Many decisions will actually involve combinations of these categories, and it is important that the trainees learn to be alert to the possible interdependencies and interactions. For example, data exchange and data management business rules may affect each other.

Table VI. Business Rule Categories with Sample Rules S1000D CATEGORY ARMY EXAMPLES PROJECT EXAMPLES

General - Overall decisions about S1000D implementation

Project business rules shall not contradict or supersede higher-level DOD or Service business rules or requirements contained within S1000D.

The project shall decide which information sets are used and the definition of their content.

Product definition - How product is structured, like the SNS rules

Standard Numbering System (SNS) shall be derived from Government Electronics and Information Association (GEIA)-STD-0007 data if available.

The project shall determine the use of the material item category code (to indicate different types of SNS applicable to an individual project).

Maintenance philosophy and concepts of operation - Content selection – breadth, depth, type

Each type of TM/IETP shall provide in detail the maintenance coverage prescribed for the applicable maintenance level(s) by the Maintenance Allocation Chart (MAC) and SMR-coded items.

The project shall decide on the needed and available values of the maintenance levels.

Security issues - Any type of data restrictions

Security classification shall be included in the DMRL.

The project shall determine the use of the protective marking “FOR OFFICIAL USE ONLY (FOUO)” for non-COMSEC publications.

31

S1000D CATEGORY ARMY EXAMPLES PROJECT EXAMPLES

Business processes - Coordination with Logistics Support Analysis, QA, training/SCORM, etc.

Programs shall submit all MIL-STD-3031 change requests to Army Logistics Support Activity (LOGSA), AMXLS-AP, Redstone Arsenal, AL 35898-5000.

The project shall specify dates for data deliverables.

Data creation - Writing and markup rules, as well as illustration/ multimedia rules

Steps shall not have titles. The project shall decide on the maximum step levels allowed.

Data exchange - Includes use of the DDN, DMRL, and CSL

The DMRL shall be maintained throughout the project enabling a mechanism to ensure that only data modules that support the maintenance philosophy are produced.

The project shall define which packaging file formats may be used to deliver change packages between vendor and customer.

Data integrity and management - Workflow and QA

Final delivery to the customer shall not include unverified data modules.

For other than final delivery, the project shall decide on whether unverified data modules can be delivered to the customer.

Data output - Page-based and/or IETP

Text shall be positioned above and below the illustration, and not on the illustration’s left or right sides.

The project shall determine if multimedia is suitable for the environment in which the project will operate.

Chapter 2.5 of S1000D deals with business rules concepts. Issue 4.0 does not specify methods for generating business rules, beyond the layered approach and the project (or organization) decision categories above. For Army work, MIL-STD-3031 and the business rules DID (DI-TMSS-81784) provide requirements and guidance for generating and documenting business rules for a project.

Joint Service Business RulesThe tier of business rules immediately below the S1000D rules includes those set up by the Joint Services IETM Technology Working Group and agreed to by each of the Services’ technical data leads. These are business rules that apply across all Services.

Some of the areas that are covered by the Joint Service business rules are as follows:Publication Module Numbering – Business rules relating to the numbering of publications and IETPs;

in particular, those related to the Publication Module Code Security and Handling – Business rules defining business processes related to security as well as

markings for classification, distribution, destruction, and handling of data Look and feel requirements – Business rules defining common presentation rules for page-based

and interactive publications Information codes and variants – Business rules defining common use for information codes and

information code variants

The Joint Service business rules are currently included in MIL-STD-3031. The business rules that are Joint Service decisions are labeled “(JS).”

32

Army Business RulesThe Army business rules in MIL-STD-3031 were extracted from approximately 20 different Army standards, including MIL-STD-40051, and reviewed by the ARMY IETM Subject Matter Expert Committee. They apply to all S1000D technical publications that support equipment and weapon systems within the Army and all land publications in the Marine Corps. These Army business rules cover requirements for operation and maintenance at all levels through overhaul (depot), including Depot Maintenance Work Requirements (DMWRs) and National Maintenance Work Requirements (NMWRs).

MIL-STD-3031 also includes Content Selection Matrices and a Functionality Matrix that are specific to Army and Marine Corps products. (The Content Selection Matrices and the Functionality Matrix will be generally familiar to anyone who has worked with MIL-STD-40051.) Not all requirements will apply to all publications, and, in a great many areas, further decisions will need to be made by the projects. (The information sets in Appendix A of MIL-STD-3031 completely replace the information sets provided in Chapter 5 of S1000D. The Functionality Matrix within Appendix D of MIL-STD-3031 replaces the one in Chapter 6.4 of S1000D.)

Trainees should be aware that the information and rules in some of the S1000D chapters reflect material that the Army does not use in its manuals. For this reason, the Army information sets do not include these topics. If, in the future, a project needs to acquire technical data in any area not described in MIL-STD-3031, it must coordinate with LOGSA to ensure consistency.

Project-Specific Business RulesThe last layer of rules is the project-specific business rules. These rules need to address all the remaining decision points. The project determines all business rules covering requirements that are specific to the individual project or organization and not common across the Army. Each of those decision points is identified as a project responsibility in MIL-STD-3031. (A command may take responsibility for these business rules or they may be may be delegated to a project or sub-project.)

These project-specific business rules are not limited to authoring or illustrating; they can address any of the decision areas noted earlier, from interfaces to functionalities to publication. Anywhere options are available, a business rule is needed to ensure consistency. Note that the project business rules must not contradict or alter anything mandatory in the S1000D schemas, S1000D’s basic philosophies, or any of the Joint Services or Army business rules—all the layers build on the business rules that already exist.

It is important to document these project-specific rules clearly to avoid misunderstandings, since some will have significant implications (for example, the rules and values to be used for attribute values). S1000D includes a BREX data module designed as a standard way to record and exchange a project’s business rules. The contractual documentation needs to include all these agreed-on business rules, so that all project partners know what is expected, and the deliverables will correspond with their customer’s expectations. (The contract may need to be updated as the need for new business rules arise. Changes to policies, business needs, equipment, or technology may all drive changes to business rules during a product’s development and life cycle.)

33

Generating and Sharing Business RulesAs noted earlier, both the business rules for the Army and the decision points for individual projects are documented in MIL-STD-3031. For a project, it is the Project Manager’s responsibility to generate the initial business rules addressing these project-level decision points. Among the functions of the project-level business rules are:

Identifying optional XML elements and attributes that a project wishes to make mandatory or prohibit

Specifying the content of the elements and attributes and values Specifying the data module coding strategy (including SNS) Defining the rules that will apply to graphics Specifying the rules for using management information like the DDN and DMRL

The first step in generating the project-specific business rules is to find the appropriate Army content selection matrix in MIL-STD-3031 (Appendix A). Both the content selection matrix (and for IETPs the Army’s tailored S1000D-based functional matrix (Appendix D)) should be completed before the remaining project business rules can be addressed, since they will guide many of the decisions. (Refer to A Closer Look: Content Selection, Functionality, & Data Module Lists.)

BREX is a data module designed for recording and exchanging business rules among all the participants in an S1000D project. These project-support data modules use XML to encapsulate all the business rules (JS/Army as well as project-specific) governing the production of the data modules. Every data module refers to a BREX, because its rules apply to the data module’s contents. The data module files can be validated through the BREX file. The contractor should be provided an Army BREX file reflecting all the business rules in MIL-STD-3031. The contractor should develop a project-specific BREX that contains the remaining project business rules.

When the contractor delivers the completed matrix with all the project-level business rules (as well as the BREX file and the completed project business rule DID (DI-TMSS-81784), the Project Manager (PM) and any Life Cycle Management Commands (LCMCs) involved need to review the documentation to make certain that all the decisions seem appropriate and do not contradict S1000D or MIL-STD-3031. Note that changes to business rules after contract award need to be agreed on by both Government and vendor, and may require another deliverable for contract modification. A CDRL item should be used to specify the delivery of updates to the business rule document. The acquisition issues associated with using S1000D are discussed in Module 5.

34

A Closer Look:Business Rules EXchange (BREX)Within the Army, all organization or project decisions are documented in either an Excel worksheet or in a Word document. These decisions can be classified as narrative or machine-verifiable decisions. A narrative decision cannot be verified by a machine, because it cannot determine the necessary information on its own. Machine-verifiable decisions are true or false decisions. This may occur when a computer can easily determine whether or not an element, attribute, or value is missing when required or included when prohibited.

A BREX is an XML-authored file which typically contains only machine-verifiable decisions. Data modules can be validated against a BREX to ensure compliance with existing and agreed decisions. Every data module must reference a BREX.

For example, an Army business rule prohibits the use of the attribute vitalWarningFlag. If a project includes this attribute anywhere in a data module and validates that data module against the Army BREX, an error will be generated in the error report or log file.

Layered BREX

There is a hierarchy to follow when it comes to BREX. The top-level BREX is provided by S1000D and references itself. Since there is currently no Joint Service BREX, the Army BREX is the next highest BREX and references the S1000D BREX. Project BREX are under the Army BREX and will either reference the Army BREX or the command BREX, if applicable. Each BREX (top level to bottom level) further restricts existing decisions and/or addresses any remaining project decision points.

For example, S1000D may allow “X” attribute the values “A-M,” but the Army further restricts the values to allow only “A-H.” A project may opt to restrict those values even further to “A-D” and would include those allowed values in their project BREX.

BREX Limitations

A BREX can check for the existence of elements and attributes (and values), but not necessarily for verbatim (boilerplate) or required content. The Army BREX will not verify compliance with every Army decision contained in MIL-STD-3031, nor is a project BREX expected to verify compliance with every documented business rule. A BREX is limited to validating only data modules, other CSDB objects are not currently supported (for example, publication modules).

35

Documenting Business RulesThe template for documenting these entire project business rules is a matrix provided by MIL-STD-3031; the downloadable Excel version is available at https://www.logsa.army.mil/mil40051/S1000D.cfm. The MIL-STD includes guidance for completing the matrix. This template should be filled out completely, and approved by the Government, before any writing can be authorized. For easy reference, the complete business rule matrix includes the following:

The paragraph number within MIL-STD-3031 that contains the decision point The title of the paragraph where the decision point occurs The S1000D chapter title where the decision point occurs The identified decision point (verbatim S1000D text if possible) Any appropriate guidance (clarifying information) The rule (text of the rule decided on, reflecting the decision made at the point in question) CDRL reference (if explicit contract language or further detail is needed) Acquisition documentation (reference for business rules that can be determined before contract

award)

A DID (DI-TMSS-81784) is also available to help with the process. It provides both guidance and references. (It also includes space for a brief project description and other information that will provide a context for those responsible for reviewing and approving the project business rules.)

In most cases, the project team will not be able to address all the project-level decision points before the contract is let. The contractor (or contractor team) will need to be involved in determining appropriate business rules for much of the content. These business rules may be the first deliverable on a contract. (As noted earlier, the contract should call for a further deliverable to be provided if new rules need to be added following the initial set.)

36

A Closer Look:Developing Project Business RulesThe objective of business rules development is to arrive at a tailored set of technical data requirements that is compliant with S1000D while at the same time meeting a specific project’s needs.

The process begins with a set of business rules decision points. The business rules decision points are extracted from the Army’s MIL-STD-3031 and documented in Appendix C. The business rules decision point list represents the tailorable opportunities available to a project.

The list should be initially pared down to remove any sections that are not applicable to a project. Some of the non-applicable decision points may have to do with the equipment (e.g., aviation-related business rules decision points can be removed for non-aviation programs) and should be indicated as not applicable (e.g., “N/A”). When appropriate, other business rules decision points should also be indicated as not applicable based on program requirements (e.g., if the program has no S1000D training requirements, the training-related business rule decisions can be removed).

As the business rules decision point list for the program is being developed, a Business Rules Working Group (BRWG) should be established. The working group should be composed of S1000D and business rule experts, equipment maintenance and operation subject matter experts, technical authors, and a Government lead. It is required that the Government lead be competent and empowered to make decisions so that discussions can be concluded when appropriate and differences of opinion can be resolved.

The BRWG should meet regularly (typically every other week via a teleconference, with occasional face-to-face meetings for larger or more complicated programs). The agenda for each meeting is prepared in advance and approved by the Government lead with the purpose of going through the list to provide project-level business rules that answer each BRD. There will typically be action items assigned from meeting to meeting to research and report back on various issues that will impact the business rules.

The process will conclude when all business rules decision points have a corresponding business rule. A written report (usually in spreadsheet format - MIL-STD-3031 Appendix C) should be developed as documentation of each business rule. It is not uncommon for additional documents to be required as well (SNS numbering documents, lists of information codes, sample data modules codes and publication modules codes, etc.).

37

SUMMARY:Business rules record the decisions made wherever alternative courses of action might be available. S1000D incorporates some, but mostly specifies where users must make choices. The responsibility for making these choices has been allocated to the Joint Services, the Army, and individual projects – three layers of rules beyond S1000D. The Army has incorporated both the JS rules and the Army rules into MIL-STD-3031. The remaining decision areas call for business rules that reflect a project’s particular requirements. These business rules need to be drafted to the furthest extent possible by the project. Rules addressing the remaining open questions will be completed by the contractor as the details of the document and its contents are worked out.

The PM must make sure that all the business rules are clearly documented and reflect the appropriate content selection for the document as well as the project functionality matrix. A business rule matrix is provided by MIL-STD-3031 for tracking all the decisions made at the project level; it is supplemented by a DID (DI-TMSS-81784) that provides further guidance for adding business rule details where needed. These should be part of the initial contract, and then be completed by the contractor and provided as a deliverable for Army approval. Updates may be needed as the contractor gets into the project. Also, the BREX module is designed for recording and sharing all the business rules applicable to a project. It too should be provided as an initial deliverable, and be updated as the project progresses.

38

EXERCISE OPPORTUNITYExercise 6 – Business Rules Working Group

The class should be divided into teams of 4 to 6 members. Each team member should assume the identity of one of the following jobs for a role-playing exercise:

Government Lead (1)

S1000D SME (1)

Equipment SME (1 or 2)

Technical Author (1 or 2)

The team should identify a piece of equipment and carry out a mock-BRWG meeting. The equipment identified can be one from an existing, planned, or hypothetical project. The agenda for the meeting is to write project business rules for the following decision points. The trainee that takes the role of the Government Lead should facilitate the discussion.

Name of the product/equipment: ________________________________________________

Describe the equipment and its mission:

__________________________________________________________________________________

__________________________________________________________________________________

__________________________________________________________________________________

__________________________________________________________________________________

__________________________________________________________________________________

39

S1000D Chapter Reference

Decision Point Business Rule

3.9.1 The project shall decide whether torequire the use of Simplified TechnicalEnglish or not.

3.9.5.1 The project shall define standard reason for update sentences to be used.

3.9.5.2.1.2 The project shall decide on the use of the attribute referredFragment. The project shall state in the business rules when referredFragment will be used and list the precautions if it is used.

3.9.5.2.1.10 The project shall decide whether an index is required and to what level indexing should be made.

3.9.5.2.1.10 If using paragraph significant data markup, the project shall decide which types of data to mark up and in what contexts.

3.9.5.2.3 The project shall decide whether or not to use the element <commonInfo>, when to use the element, and give guidance and rules that will ensure it is consistently used.

3.9.5.2.10 The project shall decide when to use the process data module.

3.9.5.2.14 The project shall decide how to populate the enumerated attribute checkListCategory.

4.3.1 The project shall decide on which model identification codes to use for the project.

5.10.2.2 The project shall decide which of the types of first verification are applied to data modules/technical publications.

5.43.2.14 The project shall decide if the element <remarks> is used in the checklist data module and how it should be populated.

6.3.1 The project shall determine if acknowledgement of alerts will be required.

40

S1000D Chapter Reference

Decision Point Business Rule

7.3.3 The project shall determine if multimedia is suitable for the environment in which the project will operate.

41

MODULE 5 - S1000D AND THE ACQUISITION PROCESSIntroductionThis training has already covered most of the ways in which S1000D differs from other specs:

The deliverable document contents will be in the form of data modules, authored in XML. The Government, the contractors, and any other stakeholders agree in advance to a set of business

rules that specify virtually all possible decisions about the document and its contents.

The database and data modules are described in Module 3. Business rules are described in Module 4. This module focuses on acquisition documents that define project requirements: the TMCP, the Statement of Work (SOW) or Performance Work Statement (PWS), project business rules, the functionality matrix, and the content selection matrices.

S1000D’s functionality matrix is described in Chapter 6.4.1 of S1000D. This matrix provides a standard format for identifying, defining, and documenting the functional requirements for a technical data project. It is accompanied by definitions for each of the functionalities identified in the matrix. Together, the matrix and tables ensure that projects and vendors will have a common, thoroughly understood basis for functionality and expectations. (The Army has customized this matrix to indicate specific requirements, but the functionalities themselves are the same.)

Verifying that S1000D is AppropriateWhile some things change with S1000D, one of the first steps doesn’t— determining the most appropriate specification to use. While S1000D offers many advantages, it may not always be the right thing to use. For new systems, the following criteria should be considered:

Is it likely that data will be reused and/or shared across multiple publications or programs?Do S1000D data modules already exist from other programs that can be reused?Do any of the unique capabilities of S1000D satisfy program requirements (e.g., process data

module, use of modular data, interaction with training data)? Is there potential for foreign military sales of the data?Does the Concept of Operations (CONOPS) or business case indicate that S1000D is a cost-effective

alternative?

If the question is whether to convert existing documents to S1000D format, a business case is especially important. Not only will all the criteria above need to be considered, but the amount of rewriting and the extent of the format conversion required will have to be justified. The cost of any conversion needs to be weighed against the expected lifespan of the equipment.

42

Deciding on an IETP and the Use of the Functionality MatrixThe Army requires that the functionality matrix be completed for IETPs, but not for page-based publications. For programs planning to implement page-based publications intended for on screen use (i.e., PDF), the functionality matrix may still be helpful. Making the decision as to whether an IETP is appropriate may be assisted by looking at S1000D’s recommendations for page-based and IETP presentations in Chapters 6.2 and 6.3, respectively.

For page-based document presentations (paper or screen), S1000D gives the typographical information needed to set up any type of output format, either via word processors or using XML editors. (A runtime database is also an output option.) Page-layout rules, information on automated presentation functions, and rules for data module presentation are included.

For IETPs, S1000D provides guidance and requirements for look and feel. It includes everything from screen size and layout to color, dialog boxes, warnings, and change markings.

When combined with MIL-STD-3031, a project has the complete set of presentation requirements for both page-based and IETP output.

While S1000D’s XML markup allows the output to be seen and used in a range of formats, each project decides the best fit for its specific equipment and end-user requirements. Style sheets can be written to present the same data module for different uses (e.g., paper, screen, PDA).

The S1000D Functionality MatrixIf an IETP is the chosen form for the technical manual being procured, the functionality matrix needs to be tackled. The standard S1000D functionality matrix, which appears in Chapter 6.4.2 of S1000D, lists nine pages of capabilities for presenting and managing various types of technical data. The functionality matrix is the tool used to document the specific functionalities required by a project, and the Army has created a tailored version for use in developing TMCPs for IETPs. That matrix is included in MIL-STD-3031 as Appendix D. A downloadable Excel file is provided on the LOGSA Web site https://www.logsa.army.mil/mil40051/mil-std-3031.cfm.

The matrix’s first column lists the possible functionalities for technical publications. They fall into the 12 categories listed below.

Table VII. Functionality Types

CATEGORY TYPES OF FUNCTIONALITIES COVEREDAccess Allow/restrict user viewing.Annotation User’s ability to add notations such as bookmarks.

Delivery and distribution How data will be moved from vendor to client to end users. Both infrastructure and costs are important considerations here.

Diagnostics and prognostics

Fault identification, from basic troubleshooting to product-integrated systems. Ability to predict degradation/failure. Again, a sizable potential cost driver.

External processes Ability to interact with external processes to retrieve/transmit information.

Graphics Potential levels of graphics display, interactivity, and navigation. Complex functionalities may have high cost and system requirements.

43

CATEGORY TYPES OF FUNCTIONALITIES COVERED

Linking Linking can be within a publication or external. Effort/cost rises for access to resources like material handling information or integration with other data.

Navigation and tracking Some navigation/tracking options are basic, but higher-complexity techniques, like dialog-driven interaction and some filtering techniques, raise costs.

Printing Output style. Defining hard-copy-style output adds to the cost/complexity of IETPs. It is not needed if an IETP will be used in an electronic environment only.

Special content Inclusion of additional data types such as audio, motion video, and animations. Content cost and performance may be issues.

Updates Choice of methodology for making updates (which includes revisions, Rapid Action Changes, etc.) can affect life cycle costs.

User operation mode The user’s ability to connect with the source of the data.

The rest of the matrix columns are as follows: Complexity (for indicating how relatively complicated the desired document would be, on a

scale of 1 to 5 – the Army has filled in this column). This can give a program some general idea of the costs associated with the various functionalities.

Requirement (for the project to indicate whether the functionality is required – partly filled in with Army requirements)

All data sets (this indicates whether the functionality will apply to all the project’s information sets – partly filled in by S1000D based on the nature of the functionality)

A column for each of the Army’s information sets (for indicating to which content each functionality will apply):

Front MatterRear MatterGeneral Information, Theory of OperationOperator InstructionsAircraft OperatorAircraft Operator ChecklistAircraft MTFTroubleshootingPMCSMaintenanceAmmunition MaintenanceParts InformationSupporting InformationAircraft MaintenanceDepot MaintenanceDepot TroubleshootingAviation TroubleshootingPreventive MaintenancePhased MaintenanceBDARDestruction to Prevent Enemy UseAuxiliary Equipment Maintenance Hand Receipt

44

Supplemental Information for COTSPreventive Maintenance ChecklistsPreparation for Shipment of AircraftStandard Generator Set - Operator/UnitStandard Generator Set - Intermediate & DepotDMWRs – Conventional and Chemical AmmunitionMunitions and Ammunition Data SheetDemilitarization of Surplus ItemsWarranty Technical Bulletin (WTB)Depot Test Equipment Lubrication Orders

The matrix can be filled out in more than one way, depending on how a project wants to use it. (Projects should provide guidance to anyone who will be contributing.) Some possible variations are as follows:

Checkmarks for those functionalities required A “Y” or “N” in every single box, to ensure that all possibilities have been considered Letters indicating an importance ranking, such as an “R” for truly required functionalities

and an “N” for “nice to have” ones (useful if cost tradeoffs are likely) A system of letters or colors to indicate further details – for example, a functionality needed

only under certain circumstances

Using the Army’s matrix ensures that all the functionalities in the IETP that is being acquired will have been accurately specified. Chapter 6.4.1 of S1000D provides standard definitions for all those terms in the matrix so that no misunderstanding of expectations occurs between the Government and bidders or vendors. Once acquisitions staff, contractors, and any other stakeholders involved have identified the appropriate content and documented all the functionalities and information sets they want, everyone will have a clear, shared understanding of what developing the technical data will entail and how the information will be provided.

The completed matrix is also a good basis for price and cost analysis. An acquisition officer can review the pricing and evaluate the costs and benefits associated with the IETP as proposed. It may be that some higher-cost functionality requirements can be traded for others with lower costs. Also, the matrix should not be considered final until prospective contractors have responded to it. Contractors may wish to propose additional functional requirements or some tradeoffs. (Of course, any added functionalities need to be reflected in the content specified and the product plan.)

45

A Closer Look: Content Selection, Functionality, and Data Module Lists The process of starting an S1000D project may seem daunting to the uninitiated; but it does not have to be complicated, especially when the process is broken down into easy to understand steps. This Closer Look section presents how the process looks for a typical project. Hopefully, you will notice similarities to processes you are familiar with relative to the use of legacy specifications.

Select manual types

Early on in a project, a program must identify what content needs to be produced. This starts with identification of the needed manual types. In most cases, the selection of manual types will be guided by the type of equipment and the maintenance philosophy or CONOPS of the program.

MIL-STD-3031 Appendix A lists a number of manual types that have been pre-defined. These manual types include all those that are typically needed by an Army program. A program should select the manual types that will be required to support their equipment. This list of publications to be prepared is the starting point for developing a technical manual outline.

Depending on the equipment, intended use, or other factors, a program may elect to combine some of these manuals into a single IETP or book, and they may elect to acquire manual types that are different than those listed in MIL-STD-3031.

The publications selected must contain, in detail, the maintenance coverage prescribed for the applicable maintenance level(s) based on the maintenance concept in accordance with the Logistics Support Analysis (LSA) or Logistics Management Information (LMI), the Level of Repair Analysis (LORA), or an approved Maintenance Plan (MP).

Select content (information sets)

Next, the program should refer to the content selection matrices that correspond to the manual types that have been identified. The content selection matrixes in MIL-STD-3031 list the content requirements for each of the Army-defined technical manual types. The program should use the content selection matrices to tailor the technical content they will require their vendor (or organic authors) to produce for their manuals.

The matrices are divided into information sets and further subdivided into content requirements. For example, Figure 8 is a portion of the Sustainment Maintenance manual type. The maintenance information set is subdivided into numerous content requirements (painting, lubrication, assembly, etc.).

46

Figure 8. Content selection excerpt

Select functionality

Next, program teams should evaluate and identify their functionality needs if they are going to be acquiring IETP data. Representatives of all project stakeholder organizations should be involved in order to ensure that all needs are covered by the solicitation. Appendix D of MIL-STD-3031 includes an Army-specific functionality matrix. This matrix is available online in Microsoft Excel format from the LOGSA Web site (https://www.logsa.army.mil/mil40051/S1000D.cfm).

S1000D Chapter 6.4 provides instructions for completing the matrix, and MIL-STD-3031 describes ways that a project can enhance the functionality identification process. Guidance or instructions regarding project–specific processes for completing the matrix should be provided to all participants. The completed matrix will become part of the contract documentation.

Information sets, content selection matrices, and SNS are tools for defining a project’s content depth and breadth. In contrast, the functionality matrix is a tool for defining the intended use and capabilities of the project’s IETP data. The functionality matrix provides a standard format for documenting the IETP functional needs of the project, using the functionalities defined in S1000D Chapter 6.4.

Develop SNS (equipment breakdown)

A program should next have a clearly documented equipment breakdown and corresponding SNS. In many cases, the SNS structure for many projects will be predetermined by the engineering data (Logistic Support Analysis Record (LSAR), or GEIA-STD-0007). Refer to A Closer Look: Standard Numbering System (SNS) for a Closer Look at SNS.

The equipment breakdown, combined with the content selection, will help a project determine the exact quantity, type, and purpose for all data modules required by the project.

Create DMRL

The Data Module Requirements List (DMRL) is used to document the data modules required for a project. The process diagram (see Figure 9) illustrates how the development of the DMRL is tied into the larger production process. The first two steps (Select Publication Types and Content Selection) were described previously in this Closer Look.

47

In the third step, Create Draft DMRL, the draft DMRL is initially derived as an output of the first two steps. The completed content selection matrices describe the content depth that is required for a project, and the information sets describe the content requirements. But both of these items lack the necessary description of depth, quantity, and other details that are required to sufficiently scope the content that must be developed. The equipment breakdown as described by the SNS closes this gap.

As an example, the content selection matrix provides a means for indicating that the project requires a maintenance publication (or maintenance content in an IETP), and it describes the breadth of the maintenance content (i.e., the procedures and content that are required within the maintenance publication). But, it does not describe the specific data modules required to deliver that content, so the data can sufficiently cover all components of the materiel as well as all configurations of the materiel.

For example, the content selection matrix may indicate that lubrication procedures are required as part of maintenance procedures, and it (along with the information set business rules in MIL-STD-3031) describes the depth that is required within lubrication instructions. It does not, however, indicate the specific components of the materiel to which the lubrication instructions apply. It is likely, even on moderately complex equipment that numerous different lubrication procedures will be needed for numerous different parts of the equipment. Each of these lubrication procedures requires a separate data module. These numerous instances can be identified by the equipment breakdown/SNS.

The functionalities defined in the project’s functionality matrix will also have an impact on the DMRL. Certain functionalities will require different types and quantities of data modules (e.g., diagnostics vs. troubleshooting).

The DMRL is the instrument used to define the quantity as well as types of data modules required by the project. In this continued example, the content selection matrix should be used by the project to indicate that lubrication procedures will be required, and that those procedures will be produced with procedural data modules using a specified information code and information name. The lubrication-related business rules provide the content requirements. The DMRL will further indicate each instance of a lubrication procedure data module that will be produced.

Ultimately, the DMRL will list every single data module required for a project. The CSDB Status List (CSL) is derived from the DMRL and is used to document the production status of each individual data module.

48

Figure 9. Production process

S1000D-Required Material to Be Provided in a TMCPFor S1000D technical publications, the TMCP will need the following S1000D-specific components:

Contract Line Item Number (CLIN). The CLIN for TMs should identify each publication type required to plan, maintain, operate, and support the product in question, as well as consideration for changes to each. This information should match the publication types selected by the project from MIL-STD-3031 Appendix A.

Statement of Work (SOW). The SOW describes the work the contractor is required to perform along with any Government responsibilities (such as providing source material and Government-furnished equipment). This must include references to S1000D and MIL-STD-3031.

Document Summary List (DSL). The DSL is where you list all the tailored and untailored specifications, standards, handbooks, commercial standards, project business rule Data Item Description (DID) (DI-TMSS-81784), and other items directly cited in the solicitation, contract, or contract modification.

49

Contract Data Requirements List (CDRL). This should include a reference to the project business rules DID.

Contract attachments. An attachment is any documentation that is appended to the contract which established requirements for deliverables. Attachments for S1000D contract packages can include the following:

Content Selection Matrix. These matrices (from MIL-STD-3031 Appendix A) define the specific content within each publication type that must be delivered.

Draft DMRL. The draft DMRL identifies the specific data modules that must be delivered. It is developed by extending the content selection matrix by incorporating all the considerations of the physical breakdown of the equipment.

Functionality Matrix. The functionality matrix defines the required capabilities of the delivered IETP. This is not required for page-based publication acquisitions.

Project Business Rules DID. This DID (DI-TMSS-81784) documents all the project decisions that complete the tailoring of S1000D. It includes the table found in MIL-STD-3031 Appendix C.

Contract clauses. These are terms or conditions necessary to ensure the Government receives all intended deliverables. For all S1000D contracts, this includes a clause stating that the Government has ownership rights to all the data (including any data required to generate the publication). The ownership rights should include the authority to modify, reproduce, perform, display, release, or disclose technical data.

Contractor Deliverables Related to S1000DUnder S1000D, the complete list of the deliverables required from the contractor includes some types of items that used to be provided by the Government. These contractor items (the “finals” which still need Government approval) are as follows:

The final functionality matrix (for an IETP-type TM) The final content selection matrix

The final list of all applicable information codes The final list of required manuals

The final DMRL The final list (matrix) of all project-specific business rules The completed attachment to DID (DI-TMSS-81784) The final version of the BREX module The source data for the manuals (all the CSDB objects)

Each of these items needs review and input from the contractor’s experts so that both parties can be reasonably sure that the document requirements are complete and appropriate. Note that a completed business rule matrix needs to be one of the first contractor deliverables on a project, because the writing cannot begin until the agreed upon business rules have been determined. Once the matrix has been approved by the Government, it will be incorporated into the contract. (This process takes time, especially with multiple subcontractors, but ensures interoperability among the various sources’ inputs.) The CDRL for this deliverable item should also specify the delivery of updates as the need for additional business rules arises.

50

Of course, the most important S1000D deliverable that is the responsibility of the contractor is the technical data itself (data modules, publication modules, graphics, etc.). The contractor will also provide a status briefing at Government-directed In-Process Reviews (IPRs) of the data modules, typically at the 30%/60%/90% points. If the contractor or its team members are new to working with S1000D, however, a review of both XML and printable versions at an earlier stage might be appropriate.

A Closer Look:Developing ContentThis training class is not intended to provide any authoring or XML training, but it is important for participants to have an understanding of the content development (or authoring process) to the extent that it impacts deliverables. The contract documents will specify every data module that must be delivered by what is listed in the DMRL. Technical authors will use this list as the highest level guide that tells them what work they must accomplish. Other information (MIL-STD-3031, the project business rules, the CONOPS, and the equipment itself) will provide them with more detailed instructions about the content they must produce. The writing process includes the development of draft or “in-work” data modules. These data modules are in various states of completion as they are written, revised, validated, quality assurance (QA) checked, and verified. Throughout this process, the metadata (in the status section of each data module) is updated to reflect the current state of the in-work data module. The status of the data module can be determined by the metadata in the status section. At each revision of the process, the in-work number (attribute inWork) is incremented for version control. The issue number for all new, unreleased data modules is zero (i.e., issueNumber=000). Similarly, the state of the QA process can also be checked.When a data module has been verified and is released into a production environment (e.g., published in a manual or change package), the in-work number is set to 00 and the issue number is incremented by one. This metadata is the information used to confirm that the most current data is being used.In S1000D, the validation process is called “first verification,” and the verification process is called “second verification.”The originator of the data modules will use the CSDB Status List (CSL) to communicate work progress. The CSL will indicate the current state of completion (i.e., the in-work numbers and issue numbers) for every data module in the CSDB. It is important for a project to understand that only completed data modules should be considered for 30/60/90 IPRs. For example, the project team should be reviewing the first 30% of the completed data modules at the 30% review. They should not be reviewing when 30% of the entire data set is complete (which could include 100% of the data modules that are 30% complete). It is a wasted effort to review partially completed data modules.Making changes to data modules is similar (in terms of the use of the metadata in the status section) to creating a new data module. A data module that requires a change will have an established issue number that will be unchanged while the data module is being revised. The in-work number will increment through each step of the process (just like with a new data module). When the data module has been verified and ready for publication, the issue number is incremented by 1 and the data module is ready for distribution in a change package or in a revised IETP.

51

Standards, Specifications, and Policies That Apply with S1000DAcquisition standards and specifications. The following are standards and specifications that will apply with S1000D are included in the Document Summary List:

S1000D, International Specification for Technical Publications Utilizing a Common Source Database

MIL-STD-3031, Army Business Rules for S1000D: International Specification for Technical Publications Utilizing a Common Source Database

GEIA-STD-0007, Government Electronics and Information Association GEIA-STD-0007 Logistics Product Data

MIL-STD-3008B, Interactive Electronic Technical Manual (IETM) Technical Data Requirements to Support the Global Combat Support System – Army

MIMOSA, Machinery Information Management Open Systems Alliance (MIMOSA) specifications

PLCS, ISO 103030-239 Product Life Cycle Support (PLCS) Data Exchange Specifications (DEXs)

Army policies. Army policies related to acquisition of technical data are consistent with the use of S1000D and must still be followed. However, trainees also need to be aware that some of the policies are in the process of being updated to include specific references to S1000D. The following is a list of policy documents that will apply for S1000D:

AR 700-127, Integrated Logistics Support AR 750-1, Army Materiel Maintenance Policy DA Form 2028, Recommended Changes to Publications and Blank Forms DA PAM 25-30, Consolidated Army Publications and Forms Index DA PAM 25-33, User’s Guide for Army Publications and Forms DA PAM 738-751, Functional Users Manual for the Army Maintenance Management System

—Aviation (TAMMS-A) DA PAM 750-8, The Army Maintenance Management System (TAMMS) Users Manual DI-TMSS-80527B, Commercial Off-The-Shelf (COTS) Manuals and Associated Supplemental

Data MIL-HDBK-38790, Printing Production of Technical Manuals MIL-PRF-32216, Evaluation of Commercial Off-the-Shelf (COTS) Manuals and Preparation of

Supplemental Data

The following Army policies are under review to be changed to fully support S1000D: AR 25-30, The Army Publishing Program AMC PAM 25-31, Preparation of Plans for Technical Publications Verification AMC PAM 25-32, Guide for Preparation of Equipment Publications Contract Packages AMC-R 25-76, The U.S. Army Materiel Command (AMC) Equipment Publications Program AMC Form 1217, Schedule for Preparation of Equipment Publications

52

AR 750-43, Army Test, Measurement, and Diagnostic Equipment Program DA PAM 25-40, Army Publishing: Action Officers Guide AR 25-36, Interservicing of Technical Manuals and Related Technology

DOD policies. DOD policies related to acquisition of technical data are consistent with the use of S1000D and must still be followed:

DOD 5200.1-R, DOD Information Security Program DOD 5220.22-M, National Industrial Security Program Operating Manual

SummaryA detailed functionality matrix is used to define all the needs, or functions, to be satisfied by an IETP acquisition. Depending on how a program uses this matrix, not only will it provide a clear statement of expectations, but it can help with making a business case and determining possible cost/benefit tradeoffs (and even whether S1000D is the appropriate specification to use). The initial matrix can also be the basis for useful contractor input. Contractors may be able to suggest improvements both during the proposal stage and after award. Once the selected contractor has been able to review all the business rules and the other considerations that will go into producing the data modules, a final version of the matrix should be submitted to the Government for discussion, approval, and incorporation into the contract.

While the functionality matrix is a central part of an S1000D IETP acquisition, it needs to be used in conjunction with other components. The content selection matrices and business rules (see Module 4) are equally important and are still required for non-IETP documents. Other materials that will need to be part of the TMCP package are as follows:

the draft project- or document-specific SNS,

information sets,

the DID describing the project business rules (DI-TMSS-81784), and

the BREX data module that apply to the publication or publications being acquired.

Draft versions of the DMRL must also be supplied to the contractor.

Final versions of all the above items may be specified as contractor deliverables that will become part of the contract following Government approval. (The business rules in particular need to be an early deliverable, because the writing cannot begin until the business rules have been approved.) In addition, the contractor will provide the source data and status reports at IPRs (especially important for contractors new to S1000D).

53

MODULE 6 - REQUESTING A CHANGE IntroductionLike all good standards MIL-STD-3031 and S1000D will evolve over time to satisfy changing requirements and to take advantage of changing technologies. Both standards rely on their user communities to drive advancement and both standards have an established process in place to manage their respective changes. This module will help users understand the S1000D change process—including the specific part of the process managed by the Land Working Group, as well as the MIL-STD-3031 change process.

The Land WG Process to Change S1000DTo understand the S1000D change process, it is first necessary to understand the management structure of the S1000D organization because different parts of the organization are responsible for different steps of the process. As explained in Module 2, the Land WG is a function of the USSMG, which in turn is a function of the Steering Committee. The EPWG is also a subordinate of the steering committee. All Change Proposal Forms (CPFs) that originate from the Army or Army programs are first vetted by the Land WG, then the USSMG, and then the Steering Committee (and EPWG). The life cycle of a CPF is illustrated in Figure 10.

Figure 10. The CPF Life Cycle

* CPF stages (more information may be obtained from http://public.s1000d.org/ChangeProposals/Pages/CPFProcess.aspx)

Identification of the Change (The Land WG process)

The change process begins when someone identifies the need for a change. This typically happens when an Army program identifies a requirement that cannot be satisfied with S1000D. It can also happen, although it is less common, that someone identifies an error in S1000D.

54

When a need for a change is identified, the author must submit the idea using the Land WG process. The Land WG process is illustrated in Figure 11.

Figure 11. The Land WG CPF Process

The CPF author first submits the identified change to LOGSA in the form of the presentation. The presentation should have enough detail to clearly identify the change and why it is needed. A Microsoft PowerPointTM template is used to present the relevant information. LOGSA performs an initial review to verify that the change request is valid. It is sometimes the case that a program misinterprets an S1000D requirement and an explanation may negate the need for the change request.

After LOGSA verifies the validity of the change request, it is presented to the Land WG. The Land WG meets monthly to review new change proposals and to discuss other issues relevant to S1000D and the Army. Exact meeting schedules and the presentation template can be found at the Land WG Web site (https://ussmg.btas.com/lwg/).

The Land WG will review the presentation and consider if the change request is valid for S1000D. It is possible at this stage that an alternative solution (that does not involve a change to S1000D) for the author's problem is identified. If the Land WG agrees that the change request should move forward, the author must submit an official CPF to www.s1000d.org. This concludes the Land WG’s role in the submission of the CPF (although it will likely be involved again later as the technical solution is developed and reviewed).

Submit the CPF

It is the CPF author’s responsibility to submit the change proposal using the form on www.s1000d.org. In addition to administrative information, the form requires narrative text explaining the “Change you think is necessary” (a brief statement as to why the change is needed) and the “Reason for your change” (a brief explanation as to the reason behind your change). For most CPFs, a white paper providing additional details and justification is also required. A thorough CPF author will include the white paper as an attachment when the CPF is first submitted. Information from the Land WG briefing can be used to complete the white paper. When the CPF form is completed, the CPF is considered a DRAFT CPF and a temporary tracking number is assigned to it.

USSMG Review

When a U.S. entity (such as an Army program) submits a CPF, the USSMG is notified and that CPF is added to the next meeting agenda. The USSMG also meets monthly (meeting details can be found at https://ussmg.btas.com). Much like the Land WG, the USSMG reviews the change proposal. It is not uncommon that the change is something that is also desired by one of the other Services. If the author is fortunate, someone from one of the other Services may even volunteer to assist with the technical solution and defense of the CPF.

55

NEW

Once the CPF is approved by the USSMG, the CPF status is changed to NEW and the CPF is assigned an official S1000D CPF identifier. The identifier will look something like this: “2010-055-US CPF_TITLE.” The first four digits are the calendar year of submission and the next three indicate the number assigned to the CPF (in this example the CPF is #055 or the 55th CPF submitted in 2010). The next two characters indicate the entity (usually a nation) that submitted the CPF. And the final portion of the identifier is the title that is given to the CPF by the author when it was first submitted.

The NEW CPF is reviewed by the steering committee to determine if there is agreement with the business case (or “reason for change”) identified in the CPF. The business case is the justification of the problem the CPF is trying to solve or the requirement the CPF is trying to satisfy. At this review, the technical solution (if it exists yet) is not part of the consideration. If the steering committee agrees with the business case, the CPF is promoted to CANDIDATE.

CANDIDATE

A Candidate CPF must be updated to propose a solution to the problem, or the details of the change requested. This is communicated to the steering committee via updates to the white paper associated with the CPF. It is possible that there are several solutions to the problem; each should be addressed in the white paper along with benefits and costs, if possible. The steering committee will use this information to determine the way forward. The steering committee will review the information provided by the author in the white paper and make a decision about the way to resolve the problem identified (as the business case of the CPF). Once a solution has been generally accepted, the CPF is promoted to IN-WORK.

IN-WORK

It is during the IN-WORK stage that the technical solution and all related documentation are developed. The author is responsible for providing all schema changes (via a Schema Proposal Form), all chapter text changes (via an updated white paper), and updated Bike sample data, if applicable. It is important to understand that the author is responsible for providing chapter text for all areas of S1000D that are affected by the change. Depending on the complexity of the change, this might mean one or many chapters.

It is often the case (and always the case when schema changes are involved) that the EPWG will need to review and approve the technical changes in the CPF. It is recommended that the author participate in the relevant EPWG meetings so the proposed concepts can be reviewed more effectively.

The IN-WORK phase can often involve several cycles of reviews by the steering committee and the EPWG with rework by the author in between. It is important to remember that S1000D is an international specification with a wide variety of users and it sometimes takes a lot of work to come to consensus on changes.

After the steering committee is satisfied with the technical solution and all required documentation is updated and submitted, the CPF is promoted to PENDING APPROVAL.

It should be noted that in some cases, this steering committee review process is truncated and a CPF may advance through multiple levels in one meeting. For example, if a CPF is submitted that recommends only a text change to S1000D and the original white paper contains all the necessary information (well documented business case and revised chapter text), the CPF might progress from NEW all the way to PENDING APPROVAL in a single meeting.

56

PENDING APPROVAL

The PENDING APPROVAL CPF is agreed and approved as a change to the next issue of S1000D. The approval is only considered pending because the CPF must be combined with all the other CPFs that have been submitted and advanced to PENDING APPROVAL. It is possible that when the CPF is combined into the draft chapters with the other CPFs, conflict may occur. These conflicts need to be resolved and approved by the steering committee.

When it is time to begin production of the next release of S1000D, the CPF author is expected to be on the chapter authoring teams for any chapters that the CPF affected. The role of the CPF initiator is to ensure that the CPF is properly integrated into the chapter and that all conflicts are resolved.

APPROVED

Once the chapter is completed, and approved by the steering committee, the CPF is finally considered APPROVED. The work of the author is complete also.

This may seem like a daunting process—and it can be. The amount of work involved is typically related to the complexity of the proposed change. Most CPFs do not require a significant time commitment. But it is important that the author monitor the progress of the CPF very closely. It is the responsibility of the author to make sure they attend and are prepared for all necessary review meetings.

The MIL-STD-3031 Change ProcessThe MIL-STD-3031 change process was developed to be a simple and transparent way to facilitate changes to the standard. It is important to LOGSA that the process is easy for stakeholders to understand and participate in and that there is open communication regarding the disposition and status of change requests. The process is illustrated in Figure 12.

Figure 12. The MIL-STD-3031 Change Process

57

MIL-STD-3031 was published in September 2009, and preparations began immediately for a Change or Revision of the standard. Each of the validated suggestions was documented and assigned to one of three categories:

Editorial issues that could easily be implemented

Technical issues that had clear definitions of the problems and the solutions (these technical issues are called “no-brainers”)

Technical issues that require additional dialogue to determine a resolution

A complete list of all the documented issues is posted to the LOGSA web site (https://www.logsa.army.mil/mil40051/S1000D.cfm).

LOGSA conducts meetings where the more complex technical comments against MIL-STD-3031 are discussed and resolved. The review meetings will continue until all of these technical issues are resolved.

LOGSA will also make a determination about potentially expanding the scope of MIL-STD-3031. There are several areas of S1000D that, by design, have no current Army business rules. It is possible that these areas may be addressed in future releases of MIL-STD-3031. These areas include applicability, wiring, training, and technical information repositories.

All the approved changes will be incorporated into a draft update of MIL-STD-3031. That document will be the coordination version of the standard that will then follow the normal Army coordination process.

58

APPENDIX A - AN EAGLE’S-EYE VIEW OF THE ENTIRE S1000D SPECIFICATION IntroductionThis appendix takes a closer look at the contents of S1000D Issue 4.0 than occurred in Module 2. The two-page table in Module 2 is expanded in this appendix to 11 pages. This appendix is designed to give both authors and acquisition professionals a feel for what they will need in order to become familiar with S1000D. Almost no one will have to read S1000D in its entirety. Much of the information is intended for reference. The Army is using a different set of information sets, essentially eliminating multiple chapters. Also, there is a lengthy section that provides guidance for writing. It is to be referred to only as needed as each type of data module is being drafted.

This training module follows the basic structure of S1000D itself: S1000D front matter Chapter 1 - Introduction to the specification Chapter 2 - Documentation process Chapter 3 - Information generation Chapter 4 - Information management Chapter 5 - Information sets and publications Chapter 6 - Information presentation/use Chapter 7 - Information processing Chapter 8 - Standard Numbering Systems, Information Codes , and Learn Codes Chapter 9 - Terms and Data Dictionary

Figure 13 illustrates where the various chapters of S1000D come into play as a document is created in a typical production scenario.

As trainees learn about the chapters below, it would be helpful if they also look at an electronic copy of Issue 4.0. Each chapter, whatever its outline level, has a linked sub-Table of Contents at its start. This makes it easy to locate the areas of most interest to particular users and helps introduce them to how the information they need is being presented. Some of the sections (subchapters) are long, but their structure—as might be expected for an electronic approach to publications—is a logical set of nested information that is presented as it becomes relevant. (Cross-references between chapters are provided, but the authors have done what they could to make chapters easy to follow without constantly clicking the links in the PDF file.) The first section in many of the chapters, even several levels down, is often an introduction or general discussion, which is why some of the descriptions below start with a ”.2.”

59

Figure 13. Basic S1000D Process

S1000D Front MatterS1000D begins with legal notifications (e.g., usage rights), provides a table of the many changes made in the latest version (Issue 4.0), and then presents a six-page Table of Contents. This table provides links all the way to sixth-level heads, so it can instantly send users to whichever sub-sub-sub-sub-subchapter they need to reference.

Chapter 1 - Introduction to S1000DChapter 1 provides general information about S1000D. Chapter 1.1 gives history, Chapter 1.2 discusses the modular-publication concept, and Chapter 1.3 explains how to use S1000D. (Module 2 of this training guide covers these areas.) Chapter 1.4 refers to the other chapters that have information on how to tailor S1000D. For LOGSA, the place to start is the business rules, which were introduced to in Module 4 of this guide. Chapter 1.5 addresses how to request that a change be made to S1000D. This procedure is also described near the end of Module 5.

60

Chapter 2 - Documentation ProcessChapter 2 explains the generic documentation process and how S1000D fits into it. Chapter 2.2 lists applicable standards and Chapter 2.3 provides related processes. Chapter 2.4 will eventually be devoted to an implementation guide. Chapter 2.5 discusses business rules; Chapter 2.5.1 describes business rule categories and layers; Chapter 2.5.2 will eventually cover business rule generation. Module 4 of this guide discusses the applicable business rules in some depth.

Chapter 3 - Information GenerationThe fun really begins with Chapter 3. This chapter provides general rules that apply to technical publications that are produced on the basis of the data module and CSDB concepts. The material on information generation is of interest primarily to authors and illustrators, but some of it applies to acquisitions as well.

Chapter 3.1 is introductory.

Chapter 3.2 describes the structure, content, and types of the data modules. Please see Module 3 of this training guide for an overview of this topic.

Chapter 3.3 introduces the reader to information sets, which are used in specifying the desired content of data modules. Information sets define the purpose, scope, and depth of the technical information that is to be produced for operation and maintenance of a product. They are described in detail in Chapter 5 of S1000D; please see the write-up on Chapter 5 below for an overview.

Chapter 3.4 provides information and instructions for product zoning and the identification of access points. Within the data modules, designating areas and sub-areas (known as zones) helps users to locate the various equipment, assemblies, access points, and other components that make up the product. Each zone is identified by a three-digit number that indicates major structural area, zone number (which also indicates its relation to the centerline), and a sub-zone. Zone boundaries are related to physical compartment or component boundaries; for instance, a cargo door will have its own zone number. Since manufacturing build systems differ, zoning and access identifications may vary among product types or older or newer versions of a product. (This chapter also deals with the identification of access points on diagrams.)

Chapter 3.5 gives the rules for updating and releasing data modules. Data modules may need to be updated for a variety of reasons; for instance, adding new material or removing old, responding to modifications or reviews, reflecting changes in consumables, or incorporating new information gained through experience. Each project determines the appropriate frequency of updating.

The five types of updated modules are as follows: A status data module is one for which only the ID or status information needs changing. A changed data module is one in which an update affects only part of the existing module. (It

may have new elements or changes to existing elements.) Changed or reinstated-changed data modules have their changes marked and highlighted in the front matter.

A revised data module is one that has been so heavily reworked that marking changes has become impractical. (The project decides what percentage of change justifies this classification.)

A deleted data module is one that no longer applies, for reasons such as a change in configuration, but is to be retained in the CSDB.

61

A reinstated data module is a deleted data module that is again being made available for use. It can have only a status change or be changed or revised.

The three types of updated publications are as follows: IETPs are always REVISED, they are never CHANGED. If updated information is provided, the

entire IETP is considered REVISED. Printed publications can be CHANGED by the inclusion of change package data modules. Printed publications can be REVISED when CHANGES (to data modules) alter the equivalent of

75% or more of its pages.

When the updated data module is released, it will get an incremented issue number. (In-work numbers are used when information in a data module is changed during the information generation process.) The technical information repository data modules and the publication modules are also affected by the update process.

Chapter 3.6 deals with security and data restrictions. Data modules include the following four types of information relating to security:

Classification. This type of information covers defense-related classifications, both international and national, as well as commercial.

Caveats. National caveats are restrictive markings like “UK/US EYES ONLY” that complement the classification.

Instructions. These are instructions related to the distribution, export control, handling, destruction, and use/disclosure of the data module.

Information. This type of information includes copyright, policy references, and conditions that may apply to a data module.

The project security instructions normally give instructions for the control of classified data modules/technical publications. The originator of the data module is responsible for classifying its content.

Chapter 3.7 defines the how the quality of data modules and technical publications will be assured. Quality Assurance (QA) is a set of checking activities that are carried out to ensure that a product is fit for use (and technically accurate, if it is information). On military projects, fitness-for-use checking is carried out by the contractor (validation, which S1000D calls first verification), but often it is carried out by the Government (LCMC) (verification, which S1000D calls second verification). The QA requirements are defined by the customer, so the project decides which of the QA measures detailed in Chapter 3.7 are applicable. For technical information, a documented QA program is required to be part of the contract (along with a practical demonstration of first verification).

Chapter 3.8 presents the S1000D disassembly principle. Assemblies are consecutively numbered to reflect equipment disassembly and subsequent maintenance activities. These assembly numbers are then used to identify the relevant set of data modules. Note that assemblies need to be numbered with this disassembly code only if they require maintenance, have a certain level of complexity, or entail a significant volume of maintenance information. Parts and subassemblies that do not meet these requirements don’t need a disassembly code.

62

Chapter 3.9 gives a great deal of guidance on authoring in a CSDB environment. Writing documents in this environment is fundamentally different from traditional processes, though not from a work package approach. In a word processing (linear) environment, the presentation is part of the structuring and writing of a document. With an XML-based editor, the author focuses only on the information content (within the bounds of the allowed structure). The presentation is handled largely by the production and presentation application.

All data modules are produced in accordance with structural rules. Authoring rules (including front matter and warnings, cautions, and notes), illustrations, and multimedia reinforce these structural rules. Many rules are generic and apply to all data module types. Some rules are applied only to specific data module types. In addition, each project will have specific requirements in terms of the population of data modules. This is why each project must begin by producing a set of business rules that detail exactly how the project is tailoring the application of this specification (as described in Module 4 above).

Chapter 3.9.1 describes the basic writing rules for creating technical information in data modules. The rules set out the guidance for the preparation of operator and maintenance information. Note that the structure (the use of text and graphics components) explained in this chapter is valid independently of the presentation form. Authors should be aware that database-driven production can be used to produce Illustrated Parts Data and Maintenance Planning data modules.

Topics covered in Chapter 3.9.1 include: Language used and the importance of establishing a project terminology database Rules for use of abbreviations (including odd ones on equipment) and the desirability of

establishing a standard list early in the process Arranging Data Modules so that information likely to be modified can be readily changed

rather than requiring a total module rewrite Dealing with numbers, including equipment labels, fractions, and separators Units of measurement The importance of using consistent, standardized nomenclature for both illustrations/

multimedia and text Basic punctuation rules When to use uppercase (only for CAUTION and the like) and title case How to highlight – mostly bold or color except for warnings, cautions, and the like

Chapter 3.9.2 offers general guidance and rules on authoring illustrations and multimedia objects. It covers the delivery of many different media types and considers a wide range of project requirements. The project-specific business rules will play an important part in governing the delivery of the chosen media objects and types.

63

Table VIII. Contents of S1000D Chapter 3.9.2

CHAPTER TOPIC CONTENTS

3.9.2.1Illustrations and multimedia

Gives rules and guidance for creating 2-D illustrations to be presented on paper or on screen. (Some rules differ with the environment.) Covers mode of presentation, size/type/line weight, symbols, and Information Control Numbers.

3.9.2.2Navigation and configuration

Defines and explains navigation and configuration of illustrations. Includes titling and numbering; illustrating views, details, and sections; component identification; different configurations; and IPD illustrations.

3.9.2.3Use of color and photographs

Provides rules and recommendations for the use of color in illustrations and of photographic images. Includes the S1000D standard color palette.

3.9.2.4 Multimedia (general)

Provides the primary rules and minimum standards for creating audio, video, and animated 2-D or 3-D multimedia objects. Includes reminders about production and environmental considerations that can affect results, and the need to document all factors in the project requirements plan and test the implementation before delivery. Covers user interface, navigation, interactive animation, warnings, and more.

3.9.2.5 Interactive 3-D content

Covers 3-D multimedia objects in more detail, including types of media and dynamic and interactive technical content.

Chapter 3.9.3 describes the use of warnings, cautions, and notes in data modules and technical publications:

Warnings alert users to hazards associated with the materials/processes/procedures/limits that may cause injury or even death if the warning is not heeded.

Cautions alert users to possible damage to the product if the caution is not heeded. Notes provide users with helpful information that supplements the operational or

procedural information.

This chapter also presents the applicable authoring rules; for example, where the text must appear in the final product, and where in the data modules the warning, caution, or note information may be placed.

Chapter 3.9.4 offers guidance on authoring front matter in a data-module environment. The approach is fundamentally different from traditional writing, because the author has to populate data modules to reflect each of the components needed (e.g., the list of effective pages, the technical standard record, or the conditions cross-reference table). This chapter explains the requirements for each front-matter data module, and notes the areas in which each project will need to make some decisions.

Chapter 3.9.5 explains the structure of data modules, and presents the allowable content of each of the types of data module. Module 3 of this guide has more details on data module structure and contents.

64

Table IX. Contents of S1000D Chapter 3.9.5

CHAPTER TOPIC CONTENTS

3.9.5.1 Identification and status

Describes each of the elements in the identification segment and the status segment, and provides instructions for applying export control.

3.9.5.2 Content

Discusses classification, training information, and the “common constructs,” which include change marking, referencing, lists, caption groups, titles, tables, figures, hotspots, preliminary requirements, paragraphs, and controlled content. Explains how to construct each of the types of data module, with all the requisite elements and child elements and their attributes and the rules that apply. Includes the learning data module.

3.9.5.3Cross-reference tables

Deals with the applicability, conditions, and products cross-reference tables.

Chapter 3.9.6 introduces different classes of attributes, outlines the principles of how these are populated, and describes how to code project-configurable attributes. “Attributes” here means characteristics that apply to specified sets of predefined allowable values. They can be

project specific (mostly tailorable) generic (within the scope of S1000D) public (reflecting the use of material created outside S1000D)

Any tailoring required (values chosen and their interpretation) needs to be agreed on and documented in the project’s business rules.

Table X. Contents of S1000D Chapter 3.9.6

CHAPTER TOPIC CONTENTS

3.9.6.1 AttributesLists the 40 project-specific attributes, their default ranges of allowable values, and the S1000D default interpretation of these values. (28 attributes remain project-definable per MIL-STD-3031.)

3.9.6.2 Attribute coding

Describes how to code project-configurable attributes that are based on fixed values. (Currently, the only attribute in this category is quantity.) A list of the possible units and their predefined allowable values is provided as well.

Chapter 3.9.7 deals with writing data modules that contain training information. The data modules need to reflect both the appropriate maintenance data modules and the level of information the technical manual trainee needs, which in turn depends on the level of maintenance to be conducted and the complexity of the product. Training information data modules are not just procedures; they have to transfer knowledge. Sometimes, they are supplements to the maintenance data modules and provide more detailed information; other times, they have to educate the maintainer about the product itself. (Training data modules can be linked with relevant maintenance data modules either at the data module level or at deeper levels.) If training data modules are used, they are an integral part of the project’s technical information and need to be covered by the business rules.

65

Chapter 4 - Information ManagementChapter 4.1 is an introduction to information management with S1000D. Information management is the addressing, storage, and handling of objects such as data modules, illustrations, and publications in such a way that they can be easily built and shared within a project. This chapter presents the data module structure, rules for interchange of data modules, and rules for updating data modules.

Chapter 4.2 is devoted to the establishment and management of the CSDB. This training guide discusses the CSDB (and the objects stored in it) in Module 3; please see that section for a summary of the material covered in Chapter 4.2.1. S1000D also provides a list of related standards in Chapter 4.2.2.

Chapter 4.3 describes the Data Module Code (DMC), which is a part of the unique identifier of a data module. The DMC is used to manage a data module in the CSDB and to retrieve it or to gain access to it in an electronic environment. (The DMC is also discussed in Module 3.)

Chapter 4.4 specifies the coding required for the Information Control Number (ICN) that uniquely identifies each illustration sheet, multimedia object, or other data attached to a data module. Based on a Commercial and Government Entity (CAGE) code or a model identification number, the ICN is used to relate an illustration or multimedia object to one or more data modules.

Chapter 4.5 addresses the use of Data Module List (DML) and the CSDB Status List (CSL). These two lists are used to plan, manage, and control CSDB content for individual projects:

Chapter 4.5.1 defines the DMRL, which identifies all the required data modules for a particular project. The DMRL is used for planning, reporting, production, and configuration control, and is very helpful in a shared-work environment.

Chapter 4.5.2 explains the use of the CSDB Status List (CSL). When multiple agencies or companies are working together on a project, it is helpful if they periodically exchange CSL covering the status of the data modules for which each of them is responsible. (The CSL uses the same identification code, status, and data module elements as the DMRL.)

Chapter 4.6 presents the Comment form, which is used for commenting and reporting on issues related to data modules or publication modules. The commenting authority compiles the form and sends it to the module’s issuing authority, which then responds on the same form. (The commenting process is explained in Chapter 3.7, Quality Assurance.)

Chapter 4.7 gives the rules for the version control of data modules. The issue date changes and the issue number increases whenever any updates to a module are published.

Chapter 4.8 deals with the interchange of data modules. Formal standards and procedures are the best way to ensure that the interchange of data modules and other CSDB information will be both orderly and systematic, so this chapter lays out a set of general requirements for them. Each project determines the best way (given the technology available) to implement the requirements.

Chapter 4.9 explains how the publication modules are used to define, prepare, and manage data module-based publications. Like other modules, the publication module has an identification/status section as well as a content section. The content section contains references to data modules, other publication modules, and legacy publications. It is ordered and structured in the same way in which the modules need to be delivered for the final publication.

Chapter 4.9.1 defines the content and structure of the publication module.

66

Chapter 4.9.2 defines the Publication Module Code (PMC), the part of the module’s identifier that is used to retrieve, access, and manage publication modules. The code is used as an entry in the List of Applicable Publications and as a reference in data modules and publications.

Chapter 4.9.3 deals with how the author builds the publication module (which is independent of the end-user’s presentation software). It discusses the identification/status element and how the content element’s structure is defined (rather like a table of contents).

Chapter 4.9.4 covers the updating process. Updates of publications can be prepared as completely new publication modules, or by reissuing publication modules that refer to the data modules that have changed. Rules for version control are provided.

Chapter 4.9.5 presents the information needed to generate a SCORM package content module – structure, elements, attributes, etc.

Chapter 4.10 describes the BREX mechanism provided by S1000D for communicating the agreed-on business rules for a project or organization. A BREX data module describes these rules. Such a module is useful in the following ways:

To record and exchange rules while they are being developed To support correct interpretation of the CSDB objects (particularly important for security/safety) To permit validation of CSDB objects against agreed-on rules

Also, every data module must refer to a single BREX data module that contains the applicable business rules. A default BREX data module is included in S1000D. This module specifies a number of rules generally applicable to the current issue of S1000D, including the predefined value sets. Project-specific rules are then created in a separate data module and reference the Army BREX (which in turn references the default S1000D BREX); for example, specifications of elements and attributes that must or must not be applied to CSDB objects generated for the project, and the definitions of the values allowed.

If possible, a project should apply the same set of business rules to all data modules, in which case there will be only one BREX data module for the entire project.

Chapter 4.10.1 provides directions for coding BREX data modules.

Chapter 4.10.2 discusses the contents of the BREX data module.

Chapter 4.10.3 describes the default BREX data module provided.

Chapter 4.11 presents the S1000D process data module. This data module represents a procedural flow; decision points (branching), looping, selective filtering, and an external interface are supported. Typically, a process data module will represent a set of steps for a small discrete task, but it can also be used to sequence several "smaller" data modules. It is especially good for representing procedural, fault, and descriptive data.

Chapter 4.12 describes the management of multiple instances of the "same" data module. Multiple data module instances can arise because a manufacturer needs to maintain information for multiple configurations of a product. They will not apply to an Army manual.

Chapter 4.13 describes paragraph significant data and the Technical Information Repository. The Technical Information Repository is a construct not used in Army publications.

67

Chapter 4.14 deals with applicability. Applicability identifies the context for which a data module or parts of one are valid. Applicability capabilities can vary greatly, from a simple note all the way to managing the life cycle of applicability. The applicability mechanism is supported by the applicability annotation within data modules and by three specific data module types.

Chapter 4.14.1 describes the Applicability Cross-reference Table (ACT) data module, which is the central point of reference for applicability definitions. (Applicability filtering is required for customized deliveries or viewer filtering.) The ACT data module defines the product attributes, which are the properties that may affect data applicability. They are typically items such as model number that do not usually change. The ACT module can cross-reference the two tables described below.

Chapter 4.14.2 covers the Conditions Cross-reference Table (CCT) data module. This data module is used to declare conditions that affect the applicability of data and to define the incorporation status for technical conditions. Conditions are non-attribute properties that are more variable; e.g., the product’s configuration or maintenance conditions.

Chapter 4.14.3 talks about the Products Cross-reference Table (PCT) data module, which is a repository of product instances, the values for product attributes, and the conditions for each product instance. The PCT defines a product instance through a list of assignments of actual values to product attributes and conditions for the product instance. Each project determines the appropriate number of product instances for this data module.

Chapter 5 - Information Sets and PublicationsChapter 5 contains common and specific requirements for the information sets and publications needed to operate and maintain a particular type of product. It is designed for use by publication-acquisition people and authors (including illustrators). For S1000D, “information set” and “publication” are defined as follows:

An information set presents all the information needed for a specific publication, with a defined scope and depth, in the form of data modules that are managed in the CSDB. It could be called an author’s view. (The DMRL lists all the data modules required for a particular project.) Information set takes on a slightly different meaning when used in different contexts. The term information set is also used to refer to a subset of information in publications. For example, The General Information content from an Army publication can also be referred to as an information set.

A publication is information compiled and published for a customer. (It could be called a user’s view). It may be an IETP, a paper publication compiled from data modules, or a publication containing legacy data.

Please be aware that a publication may be equal to an information set. However, it may also be a subset of one; or, conversely, it may be a superset of several information sets or parts of them.

Chapter 5.2 presents the guidance for information sets and Chapter 5.3 presents the guidance for publications. However, the Army is not using the information sets from S1000D. MIL-STD-3031 includes replacement information sets (identified by content selection matrices) used by Army programs.

68

Chapter 6 - Information Presentation/UseChapter 6 provides information presentation and use rules for page-based publications (paper or screen) as well as IETPs.

Chapter 6.2 gives recommendations and examples for page-based presentation (U.S. and European sizes). It includes the typographical information needed to set up any type of output production environment, either via word processors or using XML editors.

Chapter 6.2.1 presents page-layout rules (type and image widths and heights, margins, headers/footers, etc.) for standard or oversize paper or on screen.

Chapter 6.2.2 gives detailed typographic rules and discusses automated presentation functions. The rules can be used in producing formatted output with (for example) Formatted Output Specification Instances (FOSI), Extensible Stylesheet Language (XSL), or Cascading Style Sheets (CSS).

Chapter 6.2.3 gives the rules for page based data module presentation using the layout elements given in Chapter 6.2.2. It includes detailed rules and examples for front matter, descriptions, procedures, fault information, and Illustrated Parts Data (IPD) modules.

Chapter 6.3 presents guidance for IETP look and feel and printed output from an IETP, building on Chapter 6.2.2. It covers everything from screen size to dialog boxes to change markings. Each project decides which elements of this chapter are to be mandated or to be developed for the specific equipment and end-user requirements. A functionality matrix is then used in conjunction with the information in this chapter to build the project requirement.

Chapter 6.4 describes the output functionalities that are facilitated by producing information in accordance with S1000D. It is designed to support project publication procurement and management, as well as authors, illustrators, and IT specialists. S1000D’s functionality matrix provides a standardized format for acquisition professionals to use in identifying, defining, and documenting all the functional requirements for a technical-data project. However, the Army has created a tailored version that better reflects the Army’s needs. The version for Army use can be found in MIL-STD-3031 Appendix D. Its contents are described in some detail in Module 5 of this training guide.

Chapter 7 - Information ProcessingChapter 7 provides general information; directives; and advice on the creation and maintenance of CSDB objects, generation of publications, interchange of information, and technical requirements for display systems. It describes the technical aspects of the schemas for each of the types of information objects—data modules, publication modules, and information interchange files—and covers graphics and notations, resolution of resources, and software requirements. Chapter 7 is pretty much for computer geeks, and the people for whom this training is designed (authors and acquisition staff) will not need to become very familiar with it. Aspects of concern to the acquisition process are dealt with in Module 5 of this training.

69

Chapter 8 - Standard Numbering Systems, Information Codes, and Learn CodesChapter 8 is mostly for reference. It describes the common SNSs and the ICs used in the data module code (see Module 3).

Chapter 8.2 includes the S1000D-maintained set of SNS, which is as follows:

Table XI. Contents of S1000D Chapter 8.2

CHAPTER SNSChapter 8.2.1 Generic SNSChapter 8.2.2 Support and training equipmentChapter 8.2.3 OrdnanceChapter 8.2.4 General communicationsChapter 8.2.5 Air vehicle, engines and equipmentChapter 8.2.6 Tactical missilesChapter 8.2.7 General surface vehiclesChapter 8.2.8 General sea vehicles

Note that a basic SNS can be modified to suit particular needs. In addition, a project can create its own SNS if needed, using the generic SNS provided. (See also Chapter 4.3.3 of S1000D.)

Chapter 8.3 provides examples of the use of SNS (e.g., power provision, artillery radar, software, medical, and technical publication projects). (In fact, these examples may be suitable for some projects.)

Chapter 8.4 describes the use of the ICs and presents the primary code categories. These categories are as follows:

Table XII. Information Codes

CODE INFORMATION000 Function, data for plans, and description100 Operation200 Servicing300 Examinations, tests, and checks400 Fault report and isolation procedures500 Disconnect, remove, and disassemble procedures600 Repairs and locally make procedures and data700 Assemble, install, and connect procedures800 Storage procedures and data900 Miscellaneous

Chapter 8.4.1 provides a short definition for every one of the ICs in each of those categories, and Chapter 8.4.2 provides a detailed definition. Note, however, that the Army has defined more of the information codes, so Appendix B of MIL-STD-3031 should be used instead as the reference for Army manuals. That appendix also shows the Army names for the information codes, which are usually more specific than the S1000D ones.

70

Chapter 8.5 relates to learning data and training. Chapter 8.5.1 provides codes for human-performance data, while Chapter 8.5.2 has codes related to teaching objectives, types of content, guidance, and more. (These optional codes are used in a particular element, <dmCode>.)

Chapter 9 - Terms and Data DictionaryChapter 9 is another straightforward reference resource. Chapter 9.1 provides a glossary of terms, from “airborne equipment” to “Work Sheet.” Chapter 9.2 lists the abbreviations and acronyms used within S1000D and provide some rules for their use. Chapter 9.3 defines all the types of information that can be found in the XML data element dictionary and provides a link to the Web site that has the complete dictionary.

Table XIII. Summary of S1000D ChaptersSPEC

CHAPTER MAIN TOPICSTRAINING

MODULE REF.(front

matter)List of changes Linked Table of Contents (to 6 levels)

Chapter 1 Introduction. Chapter 1.1, history. Chapter 1.2, modular-publication concept. Chapter 1.3, how to use S1000D. Chapter 1.4, refers to other chapters with information on tailoring S1000D – but the Army should start with MIL-STD-3031. Chapter 1.5, requesting a change to S1000D.

2 (intro)

Chapter 2 Documentation process. Chapter 2.2, applicable standards. Chapter 2.3, related processes. Chapter 2.4, future implementation guide. Chapter 2.5, business rules: Chapter 2.5.1, BR categories and layers; Chapter 2.5.2, future discussion of BR generation. Again, the Army should start with MIL-STD-3031

2 (intro)4 (business

rules)

Chapter 3 Information Generation. Chapter 3.1, introduction.Chapter 3.2, structure, content, and types of current DMs. Chapter 3.3, information sets, which define the purpose, scope, and depth of the technical information to be produced. (The Army will use its own.)Chapter 3.4, instructions for product zoning and identification of access points on diagrams. Each zone is identified by a three-digit number that indicates major structural area, zone number (also indicates relation to the centerline), and a sub-zone. Chapter 3.5, rules for updating/releasing DMs. The five types of updated modules are: status (ID/status only), changed (changes are marked), revised (too changed to mark), deleted (but being kept in the CSDB), and reinstated (will be treated like one of the first three types). Each project determines an appropriate frequency of updating. An updated DM gets an incremented issue number and new date. Chapter 3.6, security and data restrictions. DMs include four types of information relating to security: classification, caveats, instructions, and information. Project security instructions normally cover the control of classified DMs or technical publications. Chapter 3.7, quality assurance of DMs and technical publications. Projects decide which of the QA measures detailed are applicable. A documented QA

2 (intro)3 (CSDB and DM)

71

SPEC CHAPTER MAIN TOPICS

TRAINING MODULE REF.

program must be part of the contract (along with a practical validation). Chapter 3.8, S1000D disassembly principles. Assemblies meeting certain criteria are consecutively numbered to reflect equipment disassembly and subsequent maintenance activities; these assembly numbers are then used to identify the relevant set of DMs. Chapter 3.9, guidance on authoring in a CSDB environment, where presentation is separate from structuring and writing. Chapter 3.9.1, basic writing rules for creating technical operator and maintenance information in DMs. (The structure is independent of the presentation form.) Topics include language and project terminology, using (and standardizing) abbreviations, arranging DMs for ready modifiability, numbers, units of measurement, nomenclature for illustrations/multimedia and text, punctuation, use of uppercase and title case, and highlighting. Chapter 3.9.2, authoring illustrations and multimedia objects. Topics include navigation and configuration, use of color and photographs, and interactive 3-D content. The project-specific business rules govern the delivery of the chosen media objects and types. Chapter 3.9.3, use of warnings, cautions, and notes in DMs and technical publications, with applicable authoring rules. Chapter 3.9.4, authoring front matter in a DM environment, where the author must populate DMs to reflect each of the components needed (e.g., the list of effective pages). Projects make some of the decisions. Chapter 3.9.5, DM structure and allowable contents of each type of DM. Basic topics are the identification and status segments of the DM, the Content section, and the cross-reference tables. The Content topic is a very long chapter that discusses classification, training information, and the “common constructs,” which include change marking, referencing, lists, caption groups, titles, tables, figures, hotspots, preliminary requirements, paragraphs, and controlled content. This chapter also explains how to construct each DM type, with all the requisite elements and child elements and their attributes and rules that apply. Includes the learning data module. Chapter 3.9.6, different classes of attributes, principles of how these are populated, and how to code the project-configurable attributes. (“Attributes” here means characteristics that apply to specified sets of predefined allowable values.) Any tailoring decided on, the values chosen, and their interpretations need to be agreed on and documented in the project’s business rules. Chapter 3.9.7, writing DMs that contain training information so that they reflect both appropriate maintenance DMs and the level of information the trainee needs. (Training DMs can be linked with relevant maintenance DMs.)

Chapter 4 Information management. Chapter 4.1, introduction. Chapter 4.2, establishing and managing the CSDB Database. Chapter 4.2.2, related standards. Chapter 4.3, DMC. Chapter 4.4, coding required for the ICN that uniquely identifies each illustration sheet, multimedia object, or other data related to a DM. Chapter 4.5, the Data Module Lists: Chapter 4.5.1, the Data Module Requirement List (DMRL), which identifies all the required data modules for a particular project; Chapter 4.5.2, the CSDB Status List (CSL), which shows the current status of the modules to date.

3 (CSDB & DM)5 (S1000D

acquisitions)

72

SPEC CHAPTER MAIN TOPICS

TRAINING MODULE REF.

Chapter 4.6, the Comment form, used for commenting and reporting on issues related to DMs or publication modules. Chapter 4.7, rules for the version control of DMs; issue date changes and issue number increases whenever a module update is published. Chapter 4.8, interchange of DMs, including standards and procedures to ensure orderly exchange. (Projects determine how to implement them.) Chapter 4.9, using the publication module to define/prepare/manage DM-based publications: Chapter 4.9.1, content and structure of the publication module; Chapter 4.9.2, Publication Module Code (PMC); Chapter 4.9.3, structuring the publication module (presentation-independent); Chapter 4.9.4, the updating process, categories of updates (status only, changed, revised, deleted, and reinstated), and rules for version control; Chapter 4.9.5, information needed to generate a SCORM package content module. Chapter 4.10, the S1000D Business Rules Exchange (BREX) mechanism for communicating a project’s agreed-on business rules. A BREX data module describes these rules and every DM on a project must refer to the project’s BREX DM. Chapter 4.10.1, coding BREX DMs; Chapter 4.10.2, contents of the BREX DM; Chapter 4.10.3, a default BREX data module, to which project-specific rules are referenced. The Army BREX references the S1000D BREX and a project BREX should reference the Army BREX. Chapter 4.11, the S1000D process DM, which represents a procedural flow. It supports decision points (branching), looping, selective filtering, and an external interface. Typically, it represents a set of steps for a discrete task, but can sequence several "smaller" DMs. Chapter 4.12, managing multiple instances of the "same" data module (applies to manufacturers, but not to Army manuals). Chapter 4.13, describes paragraph significant data and the technical Information Repository. The Technical information repository is a construct not used in Army publications.Chapter 4.14, applicability (the context for which a DM is valid; often called effectivity in the Army). Chapter 4.14.1, Applicability Cross-reference Table (ACT) DM, the central point of reference, which defines the product attributes (e.g., model number); Chapter 4.14.2, Conditions Cross-reference Table (CCT) DM, which declares conditions affecting the applicability of data (e.g., a product’s maintenance conditions); Chapter 4.14.3, Products Cross-reference Table (PCT) DM, which is a repository of product instances, the values for product attributes, and the conditions for each product instance. Projects determine the number of product instances.

Chapter 5 Information sets and publications. Chapter 5.2, requirements for information sets, with guidance for preparation and coding. Chapter 5.3, requirements for publications, with instructions for material preparation and coding. The Army is not using the information sets from S1000D, so most of this material has been superseded. Appendix A of MIL-STD-3031 includes replacement information sets, with instructions for their use and the preparation of data modules.

3 (CSDB and DM)5 (S1000D

acquisitions)

Chapter 6 Information presentation and use. Chapter 6.2, recommendations and examples for page based presentation. Chapter 6.2.1, page-layout rules; Chapter 6.2.2, detailed typographic rules (for FOSI and style sheets) and automated presentation; Chapter 6.2.3, rules for page based DM presentation

5 (S1000D acquisitions)

73

SPEC CHAPTER MAIN TOPICS

TRAINING MODULE REF.

with examples. Chapter 6.3, guidance for look and feel and printed output from an IETP; project decides which elements of this chapter to use. Chapter 6.4, output functionalities facilitated by producing information in accordance with S1000D’s standardized acquisitions-oriented functionality matrix. Note that the Army has created a tailored version that better reflects the Army’s needs, which can be found in MIL-STD-3031 Appendix D.

Chapter 7 Information processing. Information on creating/maintaining CSDB objects, generating pubs, and info interchange and display systems. Technical aspects of schemas; graphics and notations; resource resolution; software requirements. Mostly for computer geeks.

5 (S1000D acquisitions)

Chapter 8 Standard Numbering System, Information Codes, and Learn Codes. Chapter 8.2, the S1000D-maintained set of SNS, which can be modified. Chapter 8.3, examples of SNS use. Chapter 8.4, use of the ICs. Chapter 8.4.1, short definitions for those ICs; Chapter 8.4.2, detailed definitions. However, because the Army has defined more of the ICs, Appendix B of MIL-STD-3031 should be used as the reference instead. Appendix B also shows the Army names for the information codes. Chapter 8.5, learning data and training: Chapter 8.5.1, codes for human-performance data; Chapter 8.5.2, codes related to teaching objectives, content types, guidance, etc.

3 (CSDB and DM)5 (S1000D

acquisitions)

Chapter 9 Terms and Data Dictionary. Chapter 9.1, glossary of terms. Chapter 9.2, abbreviations and acronyms used within S1000D. Chapter 9.3, definition of all types of information in the XML data element dictionary, with link to a Web site with the complete dictionary.

-

74