A Pragmatic Approach to Implementing S1000D Whitepaper

A Pragmatic Approach to Implementing S1000D

Introduction

ASD S1000D™ (formerly AECMA) is a non-proprietary international specification for the procurement and production of Technical Manuals, Interactive Electronic Technical Publications (IETP), for any civilian or military project.

The S1000D specification can be used for anything that requires regular maintenance or checks such as:

• air, sea and land vehicles

• equipment

• buildings and installations

In the S1000D specification these items are referred to as “Materiel”.

The ASD S1000D specification is jointly produced by the Aerospace and Defence Industries Association of Europe (ASD), Aerospace Industries Association of America (AIA), and Airlines for America (A4A), formerly known as Air Transport Association of America, Inc. (ATA), e-Business Program.

www.asd-europe.org

www.aia-aerospace.org

www.airlines.org

The specification is freely available for any industry to utilize, and is available from public.s1000d.org.

A key item to note is that ASD S1000D is a Specification, not a Standard. A specification is a detailed and exact statement of particulars. The “particulars” in this instance are the guidelines that govern S1000D. Because it is a guideline, an organization or project can adopt as much or as little as is required to achieve project outcomes.

Contents

Introduction 1

S1000D History 2

Benefits of S1000D 3

IETM vs IETP 5

Business Rules 6

Who, What, Versions and Tools 7

Summary 10

About the Author 10

Adobe FrameMaker 11Try the full functionality of FrameMaker 11 (as a part of Adobe Technical Communication Suite 4 software) in minutes and without downloading the software. Tutorials are also included. Test-drive it now at www.runaware.com/clients/adobe/techsuite.

S1000D History

S1000D has a strong history, with the growth and contribution to the specification spanning nearly 30 years. Some key dates of significance to note are:

• 1984—AECMA and the British Ministry of Defence (MoD) initiated the development of an international specification for technical publications to harmonize all existing specifications into a specification based on the Air Transport Association of America (ATA) Spec 100.

The objective of the group was to reduce any confusion resulting from existing documentation standards, by creating a common international specification for technical authoring.

• 1989—The first release of the S1000D specification.

• 1998—Initial involvement by the US Military and several key contractors to jointly develop the specification to include US concerns.

• 2002—A Memorandum of Understanding was signed between the AECMA community and the Aircraft Industries Association of America (AIA), transferring responsibility of future specification development to the AIA.

• First half of 2003—Release of “Issue 2” of the specification, which included requirements requested by the US Military and included an option to use an XML DTD or Schema.

• Latter half of 2003—First legacy data conversion to “Issue 2” during a two-phase pilot performed by Accenture and Data Conversion Laboratory for the US Department of Defense using the XML schema.

• Feb 2004—Release of Issue 2.1. This version provided for both SGML and XML data modules.

• May 2005—Release of Issue 2.2. This version provided changes across all areas of the specification based on input and change requests generated from around the globe.

• Feb 2007—Release of Issue 2.3. This version provided an additional four data module schema – Technical Repository, Container, Product Cross-reference Table, and Technical Conditions Cross-reference Table.

• March 2007—Shipping organizations and others from industry confirmed they would develop a common and shared Data Exchange Protocol based on v2.3 of the S1000D specification. This protocol is named “Shipdex” and reflects the robustness of the specification with a broad selection of commercially available software. Information about Shipdex is available at www.shipdex.com.

• July 2007—Release of Issue 3.0. This version provided the addition of a new Applicability Structure, and included a new data module schema of Applicability Cross-reference Table.

• August 2008—Version 4.0 is released. Issue 4.0 was a complete revision of the specification, which included restructuring of every data module schema type. The updated schemas included renaming of elements and new attribute structures.

• May 2009—Version 4.0.1 is released. Issue 4.0.1 included urgent changes to element and attribute usage to the v4.0 release, while waiting for the formal v4.1 release.

• Early 2013—Version 4.1 is due to formally be released in “early 2013”. It will include fixes for v4.0, plus more examples and guidance on Business Rules decision points. With this additional information, the document is expected to be around 3,400 pages.

Benefits of S1000D

The use of S1000D for projects has multiple benefits, across various areas of the business. Detailed here are the three major areas of benefit. Realization of these and other benefits will depend on the project, its implementation strategy, and technology available to the project team. Common benefits may include:

Data Planning and Management Benefits

• Interoperability at data level, through use of “accepted industry” schemas.

• Data Dictionary is freely available in the specification.

• Based on International standard ISO 8879 (SGML/XML content).

• Ease of data exchange, smaller more reusable chunks of information (data modules).

• Common information can be identified.

• Can be linked with source data such as Logistics Support Analysis Requirements (LSAR), which can be used to enhance an integrated data environment.

• Increase in data integrity and the generation of better quality documents, through data integration with other systems and business units.

• The specification permits the addition of extra documentation features such as Link mechanisms, allowing the project team to decide what level of end user experience is required.

• The data module level objects allow for the focus to be on data, as opposed to a more traditional paper delivery.

Authoring Benefits

• The focus for an author is on the content and not the formatting, reducing authoring time.

• Due to the data modules being so modular, content can be re-used across publications by up to 40%.

• Reductions in update costs by 30%, due to data module content re-use.

• Defined Document Structures allow authoring structure to be defined within programs.

• Module Uniqueness (Task /Description) allows task orientated definition.

• Compliant Authoring tools available with multiple vendors supporting the specification.

• Reduced setup costs with compliant S1000D CSDB (Common Source DataBase) Suites – multiple vendors supporting standard toolkits, features and style packs out of the box.

• When utilizing a CSDB, S1000D provides an easy roll-back to previous versions of content.

• Implementation Guidance to ease set up and assist with project decisions.

S1000D Authoring Tool – Adobe FrameMaker 11

Delivery Cost Benefits

• Non-proprietary = delivery of data to any S1000D CSDB.

• Reduced creation costs due to data re-use (see above).

• Output errors only need to be fixed once.

• Data can be unpublished for temporary or permanent removal from delivery.

• Lower document distribution costs with multiple methods of delivery available from the one source content.

• Overall streamlined publishing process.

• Lower overall costs, due to CSDB warehousing capability and multiple methods of delivery available from the one source.

• Increase in data integrity and the generation of better quality documents through data integration with other systems and business units.

• Wider access and more efficient retrieval of the documentation by the end user using the asset/equipment in the field including multiple methods of content delivery.

• Easy filtering of information, e.g. search and retrieval by applicable model, or through the use of metadata and content while searching.

The ASD S1000D Specification incorporates the planning and management, production, exchange, distribution and use of data in electronic form for different types of output, from paper/print oriented to IETP. The diagram below highlights the areas covered by S1000D.

Note that various other disciplines within the business can feed into or accept data from the S1000D data delivery and management process, hence S1000D should be part of an overall integrated business strategy to obtain maximum benefits.

Areas covered by S1000D

IETM vs IETP

With some contracts detailing a requirement to deliver IETMs (Interactive Electronic Technical Manuals) and others requesting IETPs (Interactive Electronic Technical Publications), the question is what is the difference between the two?

Interactive Electronic Technical Manual (IETM)—is a technical manual (e.g. maintenance, user training, operations, etc.) prepared or “authored” in digital form on a suitable medium by means of an automated authoring system, designed for electronic screen display to an end-user.

The functionality of IETM systems is broken down into five classes. Class 1 being an electronic book display with some basic hyperlinks for navigation from the content through to a Class 5 where documentation is integrated with systems, which may influence the display of content dynamically. Most real-world IETM systems fall somewhere in between multiple classes, in that they may have 90% of features from a class two but may also have 50% of the features from a class three and 20% of features from a class four.

The term IETM is often used for older legacy projects, which delivered various levels of electronic delivery before S1000D was quoted in delivery contracts.

Interactive Electronic Technical Publication (IETP)—as described in the S1000D specification is a set of information needed for the description, operation and maintenance of the product, optimally arranged and formatted for interactive screen presentation to the end user on an electronic display system.

IETP includes conditional branching mechanisms that can be based on user feedback. Parameters are evaluated at run-time and their values can depend on context and specific user input.

An S1000D IETP is built on the outlined functionality (Chapter 6.4) and presentation (Chapter 6.3) that is described in v4.0 of the S1000D specification. The Functionality Matrix as included in the specification displays levels of complexity and advises users that the higher the level of complexity that is involved in the S1000D IETP Viewing tool, the costs of purchasing a commercial application may be higher. However, it is possible for some S1000D IETP Viewers to be shipped with S1000D IETP content royalty free.

Example S1000D IETP

Business Rules

As described in the S1000D specification, the Business Rules are decisions, which are made by a project or an organization on how to implement S1000D. Business Rules cover all aspects of an S1000D project, and are not limited to authoring or illustrating. They do not dictate how the business is to be run, but rather how S1000D can be implemented into the organization.

The Business Rules can also address issues that are not defined in S1000D, such as rules related to how S1000D interfaces to other standards, specifications or business processes that are related to an S1000D implementation.

Can I start a project without a set of Business Rules?

Yes, but it is definitely not recommended. The business rules give you the road map or guidance on how to work within your S1000D Project, therefore the business rules should be worked on with your customer in the early stages of the project. Once the business rules are finalized they should be discussed and issued to all members of the project team, including subcontractors and the end customer to ensure consistency in implementing and accepting the project deliverables.

The ten suggested topics or categories of rules, which should be detailed in your Business Rules, are laid out in S1000D specification, Version 4.0 Chapter 2.5.1:

1. General—for overall decisions in an S1000D Project including which issue/version of S1000D, which parts will be used and a definition of terms used throughout the project which are not covered in any other categories;

2. Product definition—the data module coding as to how the product is broken down (physical or functional), model identification codes down to subsystem level, including supplier subsystems, and applicability;

3. Maintenance philosophy and concepts of operation—what information is required for the equipment, definition of item location codes, training and skill levels defined and performed in conjunction with Logistics Support Analysis (LSA);

4. Security—decide on security classes, copyright markings, use of disclosure, instructions for destruction, any national security restrictions along with restricting read/write access to content;

5. Business processes—interaction with other disciplines into Technical Publications, agreed workflow procedures between manufacturer, subcontractor and customer and reuse of content across systems including training environment;

6. Data creation—writing rules for textual data, including terminology, use of dictionaries, rules for numbers, possible use of Simplified Technical English (STE), SGML/XML mark-up rules and rules for creating graphics, including if hotspots will be used, 3D content and multimedia objects;

7. Data exchange—rules for Data Dispatch Note (DDN), Data Module Requirements List (DMRL), Data Module List (DML), CSDB Status List (CSL), frequency of data exchange. Rules for data module issue numbers and agreed criteria for acceptance and rejection;

8. Data integrity and management—workflow rules (internal and external) and Quality Assurance rules and process;

9. Legacy data conversion, management and handling—conversion rules, including mapping between elements and attributes of source and target specifications, and rules for inclusion of legacy information in technical publications;

10. Data output—which portion of content must be delivered as page-oriented or an IETP and how both of those output types should look. Will any content be output in SCORM (training) format and which content will be output in simulations? This section can also include the look and feel of the Business Rules themselves.

This is not a definitive list of categories to be included in your business rules but it is a useful guide for where to begin.

What version of the specification should I use?

The version of ASD S1000D that you use for your project will depend on factors such as:

• What you wish to achieve. If you are starting an internal project to stay ahead of your competitors in the market, one of the questions should be, what is it you are trying to gain from using the S1000D standard?

• The version the customer has specified for the project. This will be decided by the requirements of the contract. If this is not specified, it is recommended that key stakeholders are consulted and the pros and cons of each specific version of the specification are discussed.

Each version of the specification has subtle differences and functionality available for projects to use. Remember, just because the latest version of the specification has been released doesn’t mean it is needed or will meet project requirements.

Once these items have been considered and discussed, the decision can be made on what version to use. The specification version being utilized for the project should then be detailed in the Business Rules in the section titled Data Creation, as detailed above.

Who, What, Versions and Tools

Who and What

With Issue v4.0 of the specification being nearly 2,800 pages and v4.1 of the specification expected to be 3,400 pages, the immediate questions from most projects teams are:

Who—in my team needs to know about the specification?

What—does my team really need to know from this enormous specification?

The answer is of course not black and white, but “it depends”. It depends on what your customer has actually asked you to deliver and also each team-member’s role.

An individual’s role combined with what you are being asked to deliver will guide you on what areas of the specification the team needs to know immediately. Below is a Basic S1000D process diagram similar to that described in Chapter 2.1 of the S1000D Specification v4.0.

As can be seen from the diagram above, the specification is not something that should be read from front to back, but should be read based on what your project covers and where your team fits within that process.

Basic S1000D process diagram

I have outlined below a number of project scenarios to allow deliverables to be visualized against the S1000D process and the specification.

Scenario One

Scenario—You area specialist group of engineers and/or writers who have been tasked with writing technical content (Data Modules) and images for a piece of equipment to a contracted version of S1000D. You will notice in the diagram above, Chapter 1 gives you a background on S1000D including some information on tailoring S1000D to meet customer requirements together with Chapter 2, which discusses the Business Rules.

The Project Manager for a team of authors should begin by reading those first two chapters. The Project Manager will also want to obtain a copy of their customer’s Business Rules.

The Business Rules will be the guiding document for the authors to ensure the data is prepared as per the project requirements. Some understanding of Chapter 5 will also be helpful for the authors.

Your customer would issue you with the Business Rules and the list of Data Modules, together with their Data Module Codes (DMC) and Titles that authors are required to write. Based on the small component of the project you are involved in, you will probably have no requirement to maintain a DMRL and therefore will probably be no need for a CSDB or any publishing software. Based on these project requirements, Chapters 1, 2 and 5 of the specification would be essential reading for your team.

Scenario Two

Scenario—Your company is supplying an asset or piece of equipment and you have you been asked to deliver an IETM/IETP and print publications as backup for the IETP. Like Scenario One, the team will need to read up on Chapters 1, 2 and 5.

The team will also have to agree with the customer on the scope and depth of the content in preparation for developing a DMRL. To assist in preparing the DMRL the team member assigned the role of Data Module Manager, will need to ensure they are very confident with Chapters 5, 7 and 8.

With a requirement to deliver Print, you will need to finalize and document within the Business Rules the style specification you are delivering to. Often customers want content written to the S1000D specification but they expect the printed document to be delivered to an older traditional standard. Don’t panic! This is possible with the right tools.

You will then need to ensure you have discussed with the customer what features or functionality they expect from the IETP content being delivered. To ensure you have sufficient knowledge for discussions and later for delivering content in print and IETP, the person assigned to managing data delivery will need to review Chapters 3, 4, 5, 6 and 7 in depth. The Data Delivery Manager is encouraged to have the customer review the Functionality Matrix in Chapter 6 of the specification to assist in locking down both print and IETP requirements.

Once the project team has a background on S1000D and Business Rules have been developed or made available, detailing items such as the specification version for data creation, data output, and the deliverables styles, the next question is “what tools do I need as a minimum to begin my S1000D project?”

What tools do I need?

Continuing with the Project Scenarios as described previously, if you were working on Project One, you could use any Authoring Tool that is XML compliant. Before you choose a tool, you may want to assess what S1000D Packaged features the Authoring Tool contains out of the box. Tools such as Adobe FrameMaker 11 ship with authoring style sheets to common schema types and some handy utilities to make tasks such as referencing to Data Modules and Images easier.

To deliver to Project Two, you will require a much larger toolset:

1. A way to create and maintain your data – S1000D Authoring Software.

2. A way to store and retrieve your data - a Common Source DataBase (CSDB).

3. A way to manage the different revisions of your data - a CSDB Front End application or a Data Module Requirement List (DMRL) and a CSDB Status List (CSL) – managed via Data Module Management Tools.

4. A way to control the way your data is structured, presented and distributed as defined in your project Business Rules – Authoring Tool with style sheets and BREX checking.

5. A way to generate the PDF to the customer’s output specification – S1000D Binder Tool that can transform the S1000D structure to a traditional print specification output.

6. A way to generate the IETP content from the CSDB – IETP Media Generation Tool.

7. A way to present the IETP content to the end user with the functionality as requested – S1000D Viewer.

Tools in the Adobe Technical Communication Suite and Absolute Data Group’s R4i S1000D Product Suite will ensure you have a complete suite of tools to deliver to any and all of your S1000D Project requirements.

Adobe, the Adobe logo, and FrameMaker are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. All other trademarks are the property of their respective owners.

© 2013 Adobe Systems Incorporated. All rights reserved. Printed in the USA.

XXXXXXXX 3/13

Adobe Systems Incorporated 345 Park Avenue San Jose, CA 95110-2704 USA www.adobe.com

About the AuthorTammy Halter is the founder and CEO of Absolute Data Group. Tammy has been a senior technical trainer, support engineer and project manager for numerous SGML software distributors and has held the role of FrameMaker Product Engineer, (Asia Pacific & Latin America) for Adobe Systems. With over 17 years’ experience in information technology, Tammy has extensive experience in technical publishing, S1000D technical data management and information delivery systems for Defense and Aerospace. Tammy has previously served in the Royal Australian Navy Fleet Air Arm and worked for leading document management companies prior to founding Absolute Data Group.

SummaryThis whitepaper has discussed what S1000D is, the history of how it has evolved as a specification, its benefits, and things you will need to know before you get started on your first S1000D project. Things to remember:

1. The S1000D specification is a large one, but don’t be intimidated by this. The reason and benefits of a specification of this size is that it covers a lot of project requirements, examples and guidance, which assists the project team in achieving their delivery goals.

2. Focus first on the areas of the specification that you need to know based on what you have been asked to deliver.

3. Have discussions early with your customer to define exactly what it is they expect and require.

4. Make sure you have a set of business rules that will guide the team and the customer on how content will be structured, prepared and delivered, so that there are no unwelcome surprises.

5. Take your time selecting the right tools that will assist you to meet your delivery requirements, both now and into the future.