S1000D For

Beginners
 By Santanu Bag
About

This is a guide for technical writers and illustrators. The world of technical
writing is changing from the linear writing concept of a beginning, middle and
end. It is moving toward a concept of having the precise information you need
exactly when you need it in the form that suits you best given the situation you
are in right now.

The group leading the charge in this mission is the international standards
organization S1000D.

S1000D is an international specification for

the procurement and production of technical
documentation. It is a specification for
preparing, managing versions of text and
illustrations. The S1000D.org established
the standards for the exchange of
information. This is a basic overview of
technical wiring for S1000D compliance.

The purpose of this book is to provide a guide for technical writers and
illustrators who want to deliver documentation in compliance with S1000D
technical publication standards.
Chapter 1 Good Old Days of Word

Most technical writers use MicroSoft Word or a similar application to create

technical documentation. However, technical documentation is moving into
cloud databases where there is more than meets your eye.

Most standard applications we have been using for years are not up to the
requirements of the digital age. Microsoft Word and other applications simply
cannot get the job done.

What is required now is digestible meta data. Searchable connected

information and the international standards organization S1000D has defined
those data standards.

It is “open source” which means anyone can use those standards. It does not
require a specific software application, so, in theory simply producing text in
notepad will do, as long as you adhere to the rules of S1000D. And the primary
rule is that the data must be in .xml format.

XML

XML is a programming code that has been around since the 1960’s. XML
stands for eXtensible Markup Language. The programming code was designed
to store and transport data. XML was designed from the beginning to be both
human and machine-readable.

Look at it this way, XML is a set of rules for encoding documents electronically
through the use of markup. Its primary purpose is to facilitate the sharing data
across different information systems. It is a product of the World Wide Web
Consortium (W3C).

XML provides a foundation that anyone can use to build a document. It is not
proprietary nor “owned” by anyone. It does have a consortium of international
members who keep it an open, usable system for everyone. XML is used
globally. It was one of the first tools used for building websites, which became
HTML (Hypertext Markup Language).

S1000D defines the standardization of XML specifically for technical

documentation. And one of the characteristics of the S1000D is that it also uses
an “open systems” approach to the production of technical publications. The
specification does not require a specific tool or application.

XML is used by a variety of industries. Some interesting ones are Golfing:

GolfML, Aerospace:Spacecraft Markup Language, Music: Music Markup
Language, Advertising: AdXML, Artificial Intelligence: AIML and fiction
eBooks: FictionBook.

What made XML so popular is that it can be exported to iPads, iPhones,

internet web browsers, laptops, for any industry and it is adaptable.

Using music as an example, Music.XML is supported by scorewriting programs

including Finale, Sibelius and MuseScore. The Music.XML has optical
character recognition (OCR) to recognize sheet music. Most music sequencer
programs use the XML codes to get the sequence of music right. This is how
digitally music is controlled. It is also used to “code” the music. They assign
words like “acoustic” and “classical” and “jazz”. And when those are placed in a
search engine, the results are Wes Montgomery, Django Reinhardt and Pat
Metheny.
Think about that for a second. S1000D uses XML as an “open source” system
and tool independent. And provides the structure necessary for implementation
of documents and processes across distributed systems. It is powerful without
being owned by a company. It is managed by a consortium of people with
similar goals in mind — the miscibility of information for the end users.

S1000D is the resource for technical authors and illustrations. It is an XML

specification for the procurement and production of technical manuals. The
specification is freely available for any industry to utilize and available from
public.s1000D.org.

The S1000D steering committee consists of many participating organizations.

The Aerospace and Defense Industries Association of Europe. The
International Standards organization for integrated logistics support, the
Airlines for America and others.

And all of the documents are required to be delivered in XML format for
S1000D. First, before talking about XML, you need to understand how some of
the basic terms and definitions from the old days of printed copies and PDF
have changed.

eDocuments

Using Word we called it “a document”. Those who pay attention will notice that
I used the past tense for using the Word application. For those who obey the
rules of Simplified Technical English, we use the present tense. In the world of
electronic publishing (epub) we do not create “documents”. We create Data
Modules (DMs).

They are called “Data Modules” because it is all about the data. Text,
illustrations, dates, part numbers, warnings, cautions, notes. They are all
considered data.
In the old days this was the document name. In S1000D it is the Technical
Manual Identification Number (TMIN). The identification number has a
specific format. We will discuss the naming conventions for the TMIN in detail
later, but here are some examples.

TMIN Examples (http://s1000d.expert/)

Technical writers try to write a document so that the Readers will understand
what to do and how things work. And Technical Illustrators try to create
graphics so that Readers can see the components and determine the part
numbers they need.
S1000D was created to make both the text and graphical data digestible and
transferable and understandable by both the Reader and the equipment and
software program applications.

The standard for publication is more than just “text” and a “markup language”.
The S1000D is all about the data. The whole set of data: maintenance, customer
service, shipping and receiving, illustrations, parts, operating manuals and the
engineering drawings. All of it linked together in the digital format. At their
best, technical writers compile of the data into information that is useful. What
good is having the data if it is not readily available at your fingertips. Imagine
useful information that does not need to be reentered for other systems. This is
far more valuable than being handed “a PDF file” or a thumb drive with all of
your data.

This book is written to provide a general working knowledge of S1000 for

technical writers and illustrators. Here we present S1000D requirements as if
creating the manuals using the old tool MicroSoft Word application. After all, if
it is essentially the same information, how different can it be?

As different as night and day.

Headers

They’re called “Page Headers” in Word. The same things in the PDF (Portable
Document Format by Adobe) version are called “Running Heads”. However,
some of the Software applications for e-books use the term “Viewer Bars”.

Notice the Page Headers include the “security classification”.

TMIN is basically the file name of the document. We will discuss this as a stand
alone topic to understand the requirements according to S1000D.
Footers

S1000D requires that Page Footers can contain UP TO three (3) pieces of data.
Up to 3 pieces of data and not more.

Change Management

Publications have always involved the process of updating and releasing

publications with changes, revisions, deleted text, reinstated stuff. The
frequency of updating and releasing publications was decided by project.

Changes were designated using “Change Bars”, the big 4.5 point black bar that
was posted next to the stuff that changed.

Reasons for changes are summarized and recorded in the identification and
status section. We used to debate if the change bar threshold was more than
50% of the page, which made it hard to read, then we marked the footer as the
whole page was “revised” and removed the change bars.

By the time we got to revision Z, Roger lost all his hair. It had become to
unmanageable.

For S1000D all of the changes, except for editorial changes, must be marked
and provided a reason for update. The reason for update text is used to
automatically generate the Revision Summary for the technical manual (TM).

And if you think about it, it makes perfectly good sense that Changes can only
be marked for issues that are numbered 002 and above. There are lots of rules
in the game of S1000D. This one is just the beginning.

Changes to documentation requires using “elements”. The change element

looks like this: <reasonForUpdate>. The attributes, or choices for that element,
are ‘changeMark’, ‘changeType’, and ‘reaonForUpdateRefIDs’. More on this
later.

Issue Numbering

Sometimes referred to as “revision level” for the document, the “initial revision”
was designated as “IR” and then it became “Rev A”, and so forth.

S1000D revision tracking is called “Issue Number” and it starts with the draft
version which is numbered 000 and when it is approved and ready to release it
becomes the original issue 001. The next version becomes issue 002 and the
like.

Drafts

Drafts were sent out as “PDF” files and reviewed by the subject matter experts.
They ignored these drafts whenever possible. I don’t think anyone likes to read
anymore.

With S1000D drafts are designated using the attribute ‘inwork’

The attribute ‘inwork’ for the element <issueInfo> is used to track and control
the intermediate drafts until the final released issue. The initial “inwork’
number Shall be set to “01” and Shall be incremented with every change to the
data module.

Applicability

Applicability specifies parameters and associated data for a particular

installation.

For every data module (DM) there are the questions of Applicability. These are
the settings to allow the end-user to tailor their view of the publications, by
selecting a specific configuration. These are usually physical characteristics
such as color or system, component, or piece part. But it can include other
aspects of modifications such as the manual change requests (MCR), field
changes, repairs, or even environmental conditions.

Bike Example

T he international standards group created a bike example for S1000D.

Mountain Bike Manual (https://www.docuneering.com/s1000d/demo/pdf/PMC-
S1000DBIKE-C3002-LOAP1-00_000-02_EN-US.pdf)

Way Beyond Word

What makes S1000D far superior to just the written word is the data structure
for a Common Source Data Base (CSDB). The closest way I can to describe the
difference is that a word document is formed based on a formatting hierarchy.
The arrangement of the document is based on the rules of topics broken down
into smaller topics. The topics used to be called “First Order Headings”, and
topic underneath that was called a “Second Order Heading”. Each of these
nested topics would have a formatting assigned to them. The First Order
Headings were big and bold. The Second Order Headings were smaller and
maybe indented a little. You get the idea.

Common Source Data Base (CSDB)

Common Source Data Base is a structure for data more like a map or a tree. In
this structure, “Food” is called the “parent”. “Meat” and “Fruit” are called the
“child”. And in a data base, a numerical id would be assigned to each “node”.
Databases are used when there is a lot of data so that when it is populated with
all the data someone can query the database to display only the information
they need to see.
CODB Structure

This is the CODB Structure for “Food”. To display the whole “food” tree, they
would run the function with an empty string as $parent and $level = 0:
display_children (‘ ‘,0); and it would return a list of all of the food. But that
level of detail is more than you really wanted to know. So let’s move past the
Good Ol’ Days of Word to see how the “data modules” replace “word
documents. ”

When the information is obtained from the database it is written in a code. For
example this is what it looks like to ask for all of the Customers by Name and
Age.
Chapter 2 The Data Modules

T he S1000D Standard Specification

T he S1000D specification is free to download and use. The information

presented in this book is a basic introduction to the concepts of S1000D. There

is much to learn. We start with the “data module”, or some times they call it a
“data unit”. In the old days, we used to call it a “manual”.

The data modules are one component. Other components of the S1000D
specifications are introduced as we need them for a technical writing project.
First, we focus on the data modules.

The concept of a data module is not new. Teachers used to tell us “start with an
outline”. When all is said and done, a data module, it just an outline. The Data
Module is a basic outline of topics and the order in which they should be
presented in a technical document.

There is a Data Module for basically every type of technical information that is
required. This chapter provides an overview of 4 data modules. This is where
you are supposed to ask: how where they rated? rated by whom? who funded
the research for the rating? Calm thyself. It was me. I rated them based on my
opinion of which data modules a technical writer or illustrator use the most.

The Data Modules

S 1000D defines data modules as “the smallest self-contained information

unit within a technical publication”. So right out of the starting gate, we might
assume a data module (DM) as the same thing as a Word document. It would
be a starting point to understand the difference. Actually, it would be more
accurate to say that the data module is like a Word Template. So you could
assume that it would be as simple as using Word to “Save As” an “XML”
document. You could say that, but you would be wrong.

It’s what’s under the hood that counts. And we’ll get back to that in a minute.

First of all, it’s comforting to know the hard work to sort this all out was has
already been done. The AeroSpace and Defense Industries Association of
Europe (ASD) is the organization who produces standards and specifications.
They worked with Boeing, Lockheed Martin, General Dynamics and others.
Remember the Simplified English and writing rules. That was them. Remember
the iSpec220 that is “owned” by the ATA. That was them too. And now they
have created the S1000D for technical publications. The goal, of course, is to
standardize information. It all starts with various types of Data Modules (DM).

The data module types are described at www.s1000d.netTable . They are free.
The following table provides a list of my top five DMs. Remember that S100D
was developed specifically for Technical Publications, so these should sound
very familiar.

Technical manuals are created from combining data modules. The DM is a

stand alone information unit just like a chapter out of a book. Traditional
S1000D data modules are: Procedure, Description, Parts, Scheduled
Maintenance, Fault Isolation or Operational.
There is also a set of supporting data and other specific documentation to
accompany the data modules, but we will save that topic for later. The following
table present the types of data modules and a description of each of them.

Data Modules and Descriptions

Data Module Contents and Meta Data

E ach data module has a “Contents” area which is what the end user sees and

“Meta Data” that the user does not see. The contents are described by the
module name: Descriptive, Procedural, Process, etc. But an important part of
the Data Module is the Meta Data that is “under the hood”, so to speak because
it is not seen by the end user.

Under the hood, the Meta Data provide the “hooks” to find information, and
sort data. When you use an internet browser to search for “jazz, music, guitar”
the words are meta data tags which search the stored data to retrieve Fats
Waller, Diann Krall, We Mongomery, Joe Pass.

S1000D has defined the meta data. This is what enables the transport of the
documentation between various s. No matter whose data base stores the data,
the meta data is the same. No matter who wrote the application to reach the
document, the information is readable

Data Module Code (DMC)

The Data Module Code (DMC) is a unique code of short-hand information

about the data module contents. This is the standard naming convention for a
data module. DMC is an accurate description of the contents for the module
without having to open the files.

The DMC is the unique “description” for the document in short hand form.
Later on we will discuss the details, but for right now here is a preview of
upcoming events. The DMC must be included in the header information for
S1000D. The DMC contains the following information:

MODEL

The Model is the model or overall to which the technical data is applicable. My
motorcycle is an F650 model made by BMW. The model is assigned by the
company or programming manager when the data module is created for a
specific project.

SYSTEM CODE
The system is a generic method of organizing the information. The S1000D
System and Subsystem codes are extensive. The following table presents several
different codes which might be useful

Systems and Subsystem Codes and Definitions

SYSTEM DIFFERENCE CODE

T he System Difference Code indicates there are alternative versions of the

system and subsystem without affecting the type, model or variant identity. The
System Variance Codes are used to identify information that is specific to one
unique configuration.

This fits the need when there are twin models produced. For example, there is a
system number for the standard F650 right off the assembly line, and there a
code to identify the customized F650s which are created. Each customized bike
is assigned a “systemDiffCode”.

STANDARD NUMBERING SYSTEM (SNS)

T he standard numbering system is not new. The code was created a way to

break the whole assembly into smaller components. The same group that
developed the Standard Numbering System (SNS) also created the S1000D
system. Typical standard breakdown of components would be the motor, the
drive train, the electrical components.

For the aircraft industry, the ATA Standard Numbering System is provided in
the ATA iSpec 2000 reference document. This document provides the
Information Standards for Aviation Maintenance. So if you work on airplanes
and you want to know about the air conditioning system, the answer is always
the same: “Section 21”. Th the main distribution system for the air conditioning
is always in Section 21. Within the Section of Air Conditioning there are
chapters. Chapter 23 is recirculation. The “Chapter” is broken down into
additional pair of numbers. The Air Return Grill is, for example, 03 while the
sidewall risers are 04. So to find the information on air conditioning air return
grill, look in 21–23–03. If you are looking for side wall riser information go to
21–23–04. So, you will notice that the SNS is a hierarchy of three pairs of
numbers. The following table presents a examples for SNS codes for the aircraft
business.

Standard Numbering System (SNS)

DISASSEMBLY CODE

T he Disassembly Code is typically used to identify the order in which parts

are removed. This identifies the breakdown condition of an assembly to which

maintenance information applies. The pair of numbers starts with “01”.

DISASSEMBLY CODE VARIANT

U sed when two or more data modules share the same number a

disassembly code variant can be created to identify the level of disassembly for
the variation. For those who are familiar with illustration parts catalogue this is
the Alternative Logistic Control Number (ALC) or the Alternate Indentured
Product Code (AIPC).

Going back to my BMW motorcycle, I have a Tall Windshield, where other

people have a short windshield. And the directions to remove them are slightly
different for the same bike. This is a variant of the disassembled bike.

FUNCTION CODE

T he function code describes which type of directions are provided. A

function code is a 3-digit number. A short list of the Primary functional codes
are provided in the following table.

A 400 level function code provides fault reports and isolation procedures.
Whereas 500 level function codes provides instructions to disconnect, remove
and disassemble something. The following table provides a sample of the most
often used primary function codes. The entire set of function codes is literally
pages and pages of selection available.
Function Codes for Task Descriptions

FUNCTION CODE VARIANT

T he Function Code Variant is a one Letter assignment. The basic, off the

shelf item starts with the letter A. Instructions for a specific installation, or a
one-off is indicated by letter B. This provides ability to deliver specific task
instructions.

ITEM LOCATION
I tem Location code identifies the location of the unit on which maintenance

is being performed. Some maintenance is performed while it is installed on the

aircraft, which some maintenance is only performed after the item has been
removed from the aircraft and is sitting on the work bench

Together these codes for hardware and identification, the information of

primary function and learning type creates the Data Module Code (DMC). The
DMC can range from a set of 17 to 41 alphanumeric characters.

IMPORTANT TO KNOW ABOUT DMC

It is vitally important for everyone involved in the project to understand and

agree on the DMC codes before the project starts. These important variables are
used to look-up and search for information later.

These become the “hooks” by which any data is retrieved from the database. So
if you want to know which valves were installed and where three years from
now, how these fields of information are filled become vitally important. Worst
of all, if you are inconsistent in the manner in which the data is populated it will
be a giant mess.

The quality of the data out is only as good as the data put into the database.

Before the project even begins, document how the DMC is defined. Make sure
this is a “live” document and updated as the project is refined. Make sure
everyone has access to the latest and greatest copy of the document too.
Chapter 3 Elements and Attributes, Oh My!

Structured Documentation

The data modules are structured documentation. Structured documents are

made up of XML containers of information and data. Larger XML containers
are built from adding smaller ones together and more containers are added
until the structure is complete. These XML containers are called “Elements”
and each element has one or more attributes.

The completed structure is what we have always delivered to the client. A

master set of documentation providing information and guidance to maintain
whatever it is that was purchased.

It may be awkward at first to understand, but XML does not DO anything.

Here’s a short example of an XML note.

<note>

<to> Rhonda </to>

<from> John </from>

<heading> Reminder </heading>

<body> You owe me a dollar </body>

</note>

The note is called a “structured document” because it has the structure of

heading and body. It has sender information, the note has receiver information.
But still, the XML does not DO anything. XML is just information wrapped in
“tags”. For those who know that HTML is how web pages are built, the HTML
was designed to display the data with focus on how the data looks, the XML was
designed to carry data, with a focus on how the data is defined.

XML structure keeps it simple. It simplifies data sharing. It simplifies data

transport. It eliminates the problems of incompatible systems and upgrades.
The XML provides a means to store data in plain text format. This provides a
software and hardware independent way of storing, retrieving and sharing the
data. For this reason, XML makes it easier to expand and update to new
operating systems, new applications or new browsers without loosing any data.
And it all starts with a container called a “data module”.

Containers

Data Modules are made of container elements. In XML the container is the area
enclosed by the beginning and ending brackets and looks like this <container>.
If you right-mouse click on an XML document you can choose to open the
document using WordPad..

One of the more common container elements is the <Figure> element. The
figure element must contain not only the graphic image but it also needs a list
of attributes for the figure, such as the file name of the graphic, the figure title,
etc.

Because the figure element contains other elements is it called a Container

Element. Like Russian Stacking Dolls, container elements can contain smaller
and smaller other elements.

Elements
Elements have ‘names’ and the name describes the type of data they contain.
Going back to the example of the <person> element. As you would expect, the
data contains information about the person.

Some elements are considered “containers” because they contain more than
one piece of information. Typically they hold more detailed data, or attributes
about the data. The attributes stored in a data element are sometimes called
“child elements” because they are children of the main element.

Look at <person> as an element, or container. The attributes of a person could

be they are female, her first name is Anna and her last name is Smith.

Attributes

Attributes provide the details about the element.

Consider the <date> element. The attributes are “month”, “day” and “year”. But
<date> can be formatted in many different ways. Some places write Jan 07,
2021 while other places write 07 JAN 21, and it could also be seen as January 7,
2021. Or even 01/07/2021. You know what I mean.

Because there are many ways to enter the same information there are
restrictions on the values. Th next figure is an example of an element named
“initials” who is restricted to three capital letters.

No, you don’t have to know how to code. But you do have to know the rules of
entering data. And with each restriction there is a rule. The rule in this instance
means that you have to enter the text as three all capital letters.

For creating data modules, the most important things to remember are the fact
that each data module has a set of elements and attributes. Some elements and
their attributes are seen as content, while other elements and their attributes
are not seen by the user. A specific string of elements creates the Data Module
Code (DMC) — the “name” of the data module. And finally, some elements and
attributes are mandatory (M) while others are optional (O). Those are the
basics to create any data module.

Note too that not all elements are in every data module. This next figure shows
the list of element and attribute names with an “x” indicating which data
module it can be used in. For example, a <checkListProcedure> is only found in
the Checklist Data Module. However, the element <commonInfoDescrPara>
can be used in the Procedure, Fault, Checklist and Process Data Modules.

But before we get into the details of creating a data module, there are some
other terms and definitions that useful to know.

Cardinality

Cardinality is an important restriction for an element. It constraints the

number of instances (cardinality) that an element can appear in an XML
document. In other words Cardinality sets the number of times you can use an
element.

Cardinality is specified by using “minOccurs” and “maxOccurs” attributes. And

if we do not specify minOccurs or maxOccurs, the default value is 1. That means
once. There can only be one and only one occurrence of the element and it is
mandatory.

Namespaces

Namespaces are names given to specific groups of schema. For example, if we

had a schema for purchase orders, we might want names spaces for the
international purchase orders to separate them from state or regional purchase
orders.
If you look under the hood, schema elements that are associated with a
namespace have the prefix such as xsd.

Extensible Markup Language (XML)

XML is not new. It was created in 1996 I kid you not. It is an “open standard”
which means it’s free to use. But that also means it is free for everyone to
interpret the code in a way that suits their needs best. Consider yourself
warned.

XML syntax can be read by hundreds of applications including RSS, Atom,

SOAP, SVG, XHTML and even Word. I can hear you now, “here’s a quarter…”

The actual document for XML comes in two parts: the markup and content. A
whole chapter is dedicated to this later on.

The first thing for Technical Writers and Illustrators to know is that XML is a
“tree hierarchy”. The Reader’s Digest Big Print version of this means that all of
the files have to be kept to be inside the same electronic file folder. There
cannot be a separate file folder for “illustrations”.

Common Source Data Base (CSDB)

Because there are so many pieces of the XML puzzle that combine to make a
document, it is necessary to house the complete palette of elements,
illustrations and the schema in a database. The aim of the CSDB is to provide a
user friendly automatic process to build the documentation. Oh excuse me, the
proper term is called a Publication Module (PM). It’s a more accurate
description really. The final product is more than just a document or set of
documents.

Document Object Model (DOM) Parser

The DOM defines the standard for accessing and manipulating documents. It
was established by the W3C, the World Wide Web Consortium. The people who
brought you the
internet. https://en.wikipedia.org/wiki/World_Wide_Web_Consortium.

In simplified English, this means that .XML documents are “read” by a

“parser”. Just as Word is used to read .doc files, and Internet Explorer and
Google Chrome web browsers are used to view files on the internet, a Parser is
used to read the XML files.

Data Module Requirements List (DMRL)

The data module requirements list defines the data modules to be created. It is
the “intended content list” for the data base. This usually becomes the con-
tractual document, the list of deliverables between the technical
writers/illustrators and the documentation owner.

Chapter 4 Schema

When a Plan Comes Together

This chapter provides an overview of the elements and attributes specifically to
create the description and process data schema. As you recall, a schema is a
combined set of elements Many more element combos exist than are presented
here. And the descriptions of the schema presented in this book provide enough
information to get your feet wet, but not enough to make you competent at
S1000D requirements. This book was never intended to provide everything you
need to know. The purpose is to give you enough knowledge to know how
creating an XML document is way different from creating a document in word.

Pictures are Worth a Thousand Words

The following demonstrates how elements are shown as a picture. Figure 1

shows an example of the basic parent element <dmodule>. It is a container
element in the <identAndStatusSection> of a data module and contains
address and other identity elements. Graphical illustrations of an element
provide the most amount of information about any element in the smallest
amount of space. As they say “pictures are worth a thousand words”. So now
you know how to interpret an element by just looking at a picture of one.

This is where things get interesting. Patiently we will start with the elements
and attributes that are includes in every data module. Then we will address the
elements and attributes specifically for a Descriptive and Procedural modules.
We chose the Descriptive and Procedural type modules because they are used
so often.

The Element of Surprise

Hopefully there will be no surprises. Now for descriptions of some elements.

We start with the <dmodule> element because it is the first element at the top
of every data module.

dmodule
One of the first decisions is what type of data module is applicable.
Standardization of Data Modules were created by piecing together smaller
frequently used schema. These are the basic data modules, sometimes written
dmodule, or DM.

Basic data module types are named: “crew module”, “Description Module”,
“Illustrated Parts Data Module”, “Procedural Module” to name a few. Start with
the dmodule type that best describes the data.

Let’s look at a data module to see what it looks like under the hood. The
following is an illustration of a Procedural Module. The identandStatusSection
is a container type element. It contains the identExtension and the dmCode.

Remember opening the wooden Russian Nesting Doll? In this case the nesting
dolls are small schema nested inside of other schema inside other schema and
the container is called the Data Module.

And remember that each container element has a set of attributes to go with it.
The required attributes are indicated by the red boxes in the illustration.

Next let’s take a look at a few important elements. I’ll show the elements this
time in the form of a table instead of an illustration so you can see and example
of the attributes and what they mean.

dmCode

The data module code is essentially a code to tell you what is inside the data
module without having to open it. It must be a unique identifer. There can be
no duplicates. The dmCode says it all — what type of data module is used, what
stage of disassembly it is in, where it is located and other information.
The <dmCode> uses the attributes to form part of the unique identifier and it is
called the data module code.

The following provides an example of the dmCode. These attributes are at the
top of the data module. They describe what information is contained within the
data module.

dmCode

Schema
For our purposes, a Schema is a small set of elements and attributes that suit
our needs and we assign a name to it. Just like playing poker certain hands are
given names like “Royal Flush” or “Straight Flush”, the XML world has sets of
elements and attributes they define for specific uses. Publishers use the
DocBook schema or Publishing Requirements for Industry Standard Metadata
(PRISM). Vector images use the schema called Scalable Vector Graphics (SVG).
Graphical User Interfaces (GUIs) schemas as Extensive Application Markup
Language for Java (FXML) or XML User Interface Language (XUL). People
who create forms use XForms.

A schema for a document describing a website defines a website element, a

webpage element, and other elements that describe content divisions within
any page on that site.

In the bike example the schema looks like this:

<?xml version=”1.0" encoding=”utf-8"?><dmodule

xmlns:dc=”http://www.purl.org/dc/elements/1.1/"
xmlns:rdf=”http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:xlink=”http://www.w3.org/1999/xlink"
xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation=”http://www.s1000d.org/S1000D_4-2/flat
_schema/learning.xsd"> <rdf:Description> <dc:creator>U8025</dc:creator>
<dc:title>Bicycle — Performance support</dc:title> <dc:subject>Bicycle —
Performance support</dc:subject>

There is a schema for a description module and a schema for a procedural

module. There is a specific schema to create a checklist and another schema for
maintenance planning information. The most important thing to remember is
that each schema has a set of mandatory elements and attributes. The
information and the order in which the information is presented is set in stone.
Schema information is probably more than you wanted to know, so here is the
important parts to remember: There are three parts to digital documentation
technology. The XML element names define the content. In HTML for the web
browsers, these are called “tags”. The second part is called the metadata. This is
the data “under the hood” that allows the search engines to find the content.
The final part of the equation are the style sheets. The style sheets adapts
document for the various reading devices (tables, smartphones, e-readers, etc).
Chapter 5 What is an e-Book?

ePublishing

Electronic publishing is the process of issuing the modules and associated data
in machine-readable form rather than on paper. Because the content is
electronic it may be distributed over the internet and users can read the
material on a wide rage of electronic and digital devices. The names of
ePublishers is available to anyone with a Browser to search for “epublisher” and
access to the internet.

apps

Way back in the dark ages of 2010 native software applications were required to
reside on each platform. Customers are driving the manufacturer’s toward
universal device, but we are not there yet.

Amazon has Kindle. Everybook, Inc has an Everybook Dedicated Reader, the
Franklin eBookman has a device similar to the Palm Pilots and phones, but
with a larger screen. Heibook combines the XML based,OEB-compliant eBook
reader with an MP3 player and games with an audio recordder. FXPALs Xlibris
makes a high resolution tablet with a pen. Nuvomedia has an ebook device
called the Rocket eBook. There are many more.

Format

One of the more common file formats for electronic publishing is e-pub. It is a
free and open standard available in may publishing programs. Another one
is .folio which is used by Adobe for the iPad tablet and apps.
Interactive Electronic Technical Manuals (IETMs) are used by the military. The
military specification MIL-STD-40051 is the perparation of Digital Technical
Inforamtion for Interactive Electronic Technical Manuals (IETMs). Those
standards cover everything except aviation.

In computing the XML is a markup language that defines a set of rules for
encoding the documents and its information into a format that is both human-
readable and machine-readable.

S1000D is an international specification for technical publications for the

procurement and production of technical publications for aerospace, defense
and capital-intensive equipment applications. The S1000D group combined the
requirements for the maintenance and operations document into a common
source. They utilized the existing XML to create specified elements and
attributes for procedures and processes. This is the origin for the data module
types used today.

XML Parcer

An XML Parser “reads” the document. When we said that the XML is read by
both machines and people, this is the machine part of reading the XML. The
parcer provides the means to enter a new data module, access existing data or
modify the data. Essentially, it parces the data into separate parts: the data,
illustrations and the structure. There are entire books written regarding how to
implement the various parsers. We do not need to go into any of that here.

The important thing to remember for writers and illustrators about an XML
Parcer is that it performs a validation. It checks to verify that a “procedural
schema” matches the requirements defined at
the http://www.w3.org/XML/XMLSchema/. Else, the document “fails” and
isn’t even read into the system. So check your document against the applicable
schema requirements. Just exporting a document from MicroSoft Word
into .XML doesn’t cut it. Not even close.

Chapter 6 Technical Writing

This is how manuals are usually written: Tech writers and Illustrators create a
first draft of the information based on initial specifications — what the
customer said they wanted and what we said we would deliver.

Of course, by the time it’s all said and done, the final approved released
documentation barely resembles the first draft. The first draft is a total waste of
time. As part of the frustrating review process, engineers walk and talk while
they recant their adventures of 20 years ago when somebody cared. Tech
writers assemble the drafts based on the released drawings, which engineers
promptly rip apart and say those were preliminary drawings. You’d think that
by P27 the “preliminary” draft would be close. Not so much. And the process
starts over again. Finally, the document is published

That part hasn’t changed. sorry. It has just gotten more complicated.

Structured Documents

One of the reasons to migrate from the old style creating documents using
MicroSoft Word to a structured framework is work efficiency. There is a simple
misconception of how tech writers spend (or should spend) their time. This
prevailing notion believes that “writers,” spend a large part of their time
managing and publishing information and most of the time “writing”. Actually,
very little time is spent “writing”. Most of the time is spent looking for
information, or waiting for information from someone else. Because of this
misconception, it is hard for some to understand how efficiently a properly-
designed structured authoring environment could be. Technical writing has
never been about how fast you type. It has always been about how fast you can
compose and organize the content to meet all of the standards and be
understood by the end-users.

The cornerstone of any project is dependent upon the client’s understanding

and participation in that implementation. The project to move from flat files to
an object oriented database structure is no different.

What makes S1000D far superior to just the written word is the data structure
for a Common Source Data Base (CSDB). The closest way I can to describe the
difference is that a word document is formed based on a formatting hierarchy.
The arrangement of the document is based on the rules of topics broken down
into smaller topics. The topics used to be called “First Order Headings”, and
topic underneath that was called a “Second Order Heading”. Each of these
nested topics would have a formatting assigned to them. The First Order
Headings were big and bold. The Second Order Headings were smaller and
maybe indented a little. You get the idea

Common Source Data Base is a structure for data more like a map or a tree. In
this structure, “Food” is called the “parent”. “Meat” and “Fruit” are called the
“child”. And in a data base, a numerical id would be assigned to each “node”.
Databases are used when there is a lot of data so that when it is populated with
all the data someone can query the database to display only the information
they need to see.

Drafts

Drafts were sent out as “PDF” files and reviewed by the subject matter experts.
They ignored these drafts whenever possible. I don’t think anyone likes to read
anymore

With S1000D drafts are designated using the attribute ‘inwork’

The attribute ‘inwork’ for the element <issueInfo> is used to track and control
the intermediate drafts until the final released issue. The initial “inwork’
number Shall be set to “01” and Shall be incremented with every change to the
data module.

Tracking Changes

Publications have always involved the process of updating and releasing

publications with changes, revisions, deleted text, reinstated stuff. The
frequency of updating and releasing publications was decided by project

Changes were designated using “Change Bars”, the big 4.5 point black bar that
was posted next to the stuff that changed

Reasons for changes are summarized and recorded in the identification and
status section. We used to debate if the change bar threshold was more than
50% of the page, which made it hard to read, then we marked the footer as the
whole page was “revised” and removed the change bars.

By the time we got to revision Z, Roger lost all his hair. It had become too
unmanageable.

For S1000D all of the changes, except for editorial changes, must be marked
and provided a reason for update. The reason for update text is used to
automatically generate the Revision Summary for the technical manual (TM)

And if you think about it, it makes perfectly good sense that Changes can only
be marked for issues that are numbered 002 and above. There are lots of rules
in the game of S1000D. This one is just the beginning
Changes to documentation requires using “elements”. The change element
looks like this: <reasonForUpdate>. The attributes, or choices for that element,
are ‘changeMark’, ‘changeType’, and ‘reaonForUpdateRefIDs’.

ATA iSpec 2200 vs S1000D

This is for those who are writing specifically for the aircraft industry. If this is
not you, just skip it an move along.

ATA iSpec 2200

The group previously known as the Air Transport Association became the
Airlines for America. The document they provided, the ATA iSpec 2200,
provided the recommended specifications for the content, structure and
deliverables to meet the communication requirements, those being the
physical, electronic and future technologyof aircraft product technical
information.

The objective of the iSpec 2200 was to minimize the cost and effort and
exchange of information to meet the airline operational needs. the iSpec 2200
is a document-centered standard.

The iSpec 2200 provides the Document Type Definitions. The following is a
partial list:

 Aircraft Maintenance Manual

 Aircraft Illustrated Parts Catalog

 Component Maintenance Manual

 Consumable Products Manual

 Flight Crew Operations Manual

  Maintenance Planning Document

S1000D

The s1000D is a data information standard. The move from a document to a

data-centered source of information creates a modular, bite size information.
The information resides as modules in a Common Source Database (CSD). The
database is the repository for the storage of all of the document pieces required
to produce the technical publications for a project.

The S1000D basic document is a data module. A data module is the minimal
information document for exchange of information. It is the smallest and
standalone information unit conveying a particular type of information about
specific parts of the Product.

There is a Schema for each type of technical document unit. Examples of

schemas are as follows:

 proced.xsd for Procedures

 descript.xsd for Descriptions

 sb.xsd for Service Bulletins

 container.xsd for Container Data Modules

Common Information Repository (CIR) Data Module

One of the best features of modular text is that segments can be re-used. And if
the information is updated, it is updated everywhere at the same time.

The CIR is the library of standard text. For example, it would be a set of
warnings. Warn-0525 could be “DO NOT GET CLOSE TO….”
An example of CIR is as follows:

<commonRepository> <warningRepository> <warningSpec

changeType=”modify”> <warningIdent warningIdentNumber=”warn-
00525"></warningIdent> <warningAndCautionPara>Make sure that the bulb
is cool before you replace it.</warningAndCautionPara> </warningSpec> …
</warningRepository> </commonRepository>

Warnings Format

The default heading WARNING must be in 12/14 pt bold, uppercase and under-
lined centered on the width of the warning itself. This needs to be separated by
8 pt after the previous text paragraph. The actual warning text starts 8 pt
AFTER the WARNING heading. Keep the WARNING heading and the actual
warning text on the same page.

The warning text must be in 10/11 pt bold, lowercase.

Cautions Format

The default heading CAUTION must be in 12/14 pt bold, uppercase and NOT
underlined centered on the width of the caution itself. This needs to be
separated by 8 pt after the previous text paragraph. The actual warning text
starts 8 pt AFTER the CAUTIONG heading. Keep the CAUTION heading and
the actual caution text on the same page.

The caution text must be in 10/11 pt NOT bold, lowercase.

Chapter 7 The Descriptive Module

Under the Hood

For demonstration purposes, we are starting with the “descriptive Module”.

Every data module has two parts:

The schema is from the S1000D organization. At the top of the data module is a
link to the
URL http://www.s1000d.org/S1000D_4-0/xml_schema_flat/descript.xsd wh
ere it reads the schema file.

Translation and Schema XML Text

Next we introduce each of the required elements in the order in which the data
is entered. The Data Module Code (DMC) is automatically created and placed at
the top of the document, which is also a requirement of the S1000D.

identAndStatusSection

The <identAndStatusSection> provides the identity for the type of module or

work that is described and the status of the data module.
The following describes each of the component elements of the
<identAndStatusSection>.

dmAddress and dmIdent

The <dmAddress> is a container element for another container element

<dmIdent> and the element <dmIdent> is looking for information regarding
the identity for this data module.

identExtension

This is one of the Business Rules you decided. The goal is to have a unique
identification for the data modules. The <identExtension> establishes a unique
subdomain for instance identification. In other words, this is the first identifier
for the group of data modules.

It has two attributes: The (M) means it is mandatory to enter the data.

-extensionProducer (M), is typically the CAGE code of the producer of the data
module instance. Or it can be the unique number for the manual set.-
extensionCode (M), the data module extended code. The value is decided by the
data module producer.

dmCode

is the basic identify code parameters.