..
/
download
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dmodule [
<!NOTATION PNG SYSTEM "PNG" >
<!ENTITY ICN-1654N-S1000D0002-001-01 SYSTEM "ICN-1654N-S1000D0002-001-01.PNG" NDATA PNG>
<!ENTITY ICN-S1KDTOOLS-A-000000-A-KHZAE-00003-A-001-01 SYSTEM "ICN-S1KDTOOLS-A-000000-A-KHZAE-00003-A-001-01.PNG" NDATA PNG>
]>
<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_5-0/xml_schema_flat/descript.xsd">
<identAndStatusSection>
<dmAddress>
<dmIdent>
<dmCode modelIdentCode="S1KDTOOLS" systemDiffCode="A" systemCode="00" subSystemCode="0" subSubSystemCode="0" assyCode="00" disassyCode="00" disassyCodeVariant="A" infoCode="018" infoCodeVariant="B" itemLocationCode="D"/>
<language languageIsoCode="en" countryIsoCode="CA"/>
<issueInfo issueNumber="001" inWork="00"/>
</dmIdent>
<dmAddressItems>
<issueDate year="2021" month="04" day="16"/>
<dmTitle>
<techName>S1000D tutorial</techName>
</dmTitle>
</dmAddressItems>
</dmAddress>
<dmStatus issueType="new">
<security securityClassification="01"/>
<responsiblePartnerCompany>
<enterpriseName>khzae.net</enterpriseName>
</responsiblePartnerCompany>
<originator>
<enterpriseName>khzae.net</enterpriseName>
</originator>
<applic>
<displayText>
<simplePara>All</simplePara>
</displayText>
</applic>
<brexDmRef>
<dmRef>
<dmRefIdent>
<dmCode modelIdentCode="S1000D" systemDiffCode="G" systemCode="04" subSystemCode="1" subSubSystemCode="0" assyCode="0301" disassyCode="00" disassyCodeVariant="A" infoCode="022" infoCodeVariant="A" itemLocationCode="D"/>
</dmRefIdent>
</dmRef>
</brexDmRef>
<qualityAssurance>
<unverified/>
</qualityAssurance>
<reasonForUpdate>
<simplePara>Upissued</simplePara>
</reasonForUpdate>
</dmStatus>
</identAndStatusSection>
<content>
<description>
<note>
<notePara>This is a work-in-progress tutorial to introduce the basic concepts of S1000D.</notePara>
</note>
<levelledPara>
<title>What is S1000D?</title>
<para>S1000D is "an international specification for the procurement and production of technical publications". It combines common, international standards and best practices for writing and managing documentation into a single, open specification.</para>
<para>The "S" stands for "specification", and the "D" for "documentation". The "1000" is based on S1000D's predecessor, ATA Spec 100. But while ATA100 was developed specifically for technical publications in the aerospace industry, S1000D takes many of the same ideas and generalizes them for any kind of publication.</para>
<para>S1000D breaks from many of the traditional concepts of publications. These typically divide content in to "chapters", "sections", "subsections", etc. An S1000D publication, on the other hand, is topic-based and consists of units of information called <emphasis>data modules</emphasis>, which are stored in a Common Source Database (CSDB).</para>
</levelledPara>
<levelledPara>
<title>The CSDB</title>
<para>The full title of the S1000D specification is "International specification for technical publications using a common source database". The common source database, or CSDB, is where all the data for your S1000D project is stored, including the data modules. This means a data module is not tied to a particular publication, but can be reused among several publications wherever it is needed, avoiding duplication of data.</para>
<figure>
<title>Traditional publications vs. CSDB</title>
<graphic infoEntityIdent="ICN-S1KDTOOLS-A-000000-A-KHZAE-00003-A-001-01"/>
</figure>
<para>The S1000D specification does not give specific requirements for the implementation of a CSDB, and so CSDBs can be implemented in any number of ways. Often, a CSDB is built on top of an existing relational database management system.</para>
<note>
<notePara>For the purposes of the s1kd-tools, the CSDB is simply a folder in a typical filesystem.</notePara>
</note>
<levelledPara>
<title>CSDB objects</title>
<para>The CSDB is made up of many CSDB objects. These include:</para>
<para>
<randomList>
<listItem>
<para>Data modules, which represent individual topics</para>
</listItem>
<listItem>
<para>Publication modules, which place data modules in to a hierarchical structure for publishing</para>
</listItem>
<listItem>
<para>Information control numbers (ICNs), such as illustrations, which support data modules.</para>
</listItem>
</randomList>
</para>
<para>The following sections will discuss some of these different types of objects in more detail.</para>
</levelledPara>
</levelledPara>
<levelledPara>
<title>Data modules</title>
<para>The data module is the smallest self-contained unit of information in S1000D. This could be, for example, a description of how a piece of equipment was made, or a procedure to remove it from the system for maintenance.</para>
<levelledPara>
<title>Structure of a data module</title>
<para>Every data module has the same basic structure, consisting of:</para>
<para>
<randomList>
<listItem>
<para>an identification and status section</para>
</listItem>
<listItem>
<para>a content section</para>
</listItem>
</randomList>
</para>
<para>The identification and status section of a data module contains metadata about the data module.</para>
<para>The first part uniquely identifies the data module. The unique identifier for a data module is composed of:</para>
<para>
<randomList>
<listItem>
<para>a unique data module code</para>
</listItem>
<listItem>
<para>the issue of the data module</para>
</listItem>
<listItem>
<para>the language of the data module</para>
</listItem>
</randomList>
</para>
<para>The second part gives the status of the data module, including:</para>
<para>
<randomList>
<listItem>
<para>the security classification of the data module</para>
</listItem>
<listItem>
<para>who is responsible for the data module</para>
</listItem>
<listItem>
<para>restrictions on how the data module may be distributed</para>
</listItem>
<listItem>
<para>what changes have been made to the data module</para>
</listItem>
<listItem>
<para>whether the data module has been quality assurance tested</para>
</listItem>
</randomList>
</para>
</levelledPara>
<levelledPara>
<title>Data module code</title>
<para>Each data module is given a unique data module code, which identifies:</para>
<para>
<randomList>
<listItem>
<para>what part of the system the data module is about</para>
</listItem>
<listItem>
<para>what kind of information the data module contains</para>
</listItem>
</randomList>
</para>
<figure>
<title>Generic structure of the data module code</title>
<graphic infoEntityIdent="ICN-1654N-S1000D0002-001-01"/>
</figure>
<para>The first part, which identifies the piece of hardware or part of the system, consists of four major components:</para>
<para>
<randomList>
<listItem>
<para>Model identification code</para>
</listItem>
<listItem>
<para>System difference code</para>
</listItem>
<listItem>
<para>Standard numbering system</para>
</listItem>
<listItem>
<para>Disassembly code</para>
</listItem>
</randomList>
</para>
<para>The second part, which identifies the type of information contained within the data module, consists of two major components:</para>
<para>
<randomList>
<listItem>
<para>Information code</para>
</listItem>
<listItem>
<para>Item location code</para>
</listItem>
</randomList>
</para>
<para>An optional third part, the learn type, identifies information about training content. The details of this code are outside the scope of this tutorial, however.</para>
<levelledPara>
<title>Model identification code</title>
<para>The model identification code identifies the overall product or project to which a data module belongs. It consists of 2 thru 14 uppercase alphanumeric characters. It is encouraged that S1000D users register their model identification codes with the NATO Support and Procurement Agency, which maintains a list of registered codes, to avoid conflicts with other projects.</para>
<para>
<externalPubRef xlink:href="https://www.nspa.nato.int/PDF/Log/S2000M/S2000M%20MOI%20codes.pdf">
<externalPubRefIdent>
<externalPubCode>https://www.nspa.nato.int/PDF/Log/S2000M/S2000M%20MOI%20codes.pdf</externalPubCode>
</externalPubRefIdent>
</externalPubRef>
</para>
<para>An example of a model identification code might be "BIKE" if you are documenting the operation and maintenance of a line of bicycles.</para>
</levelledPara>
<levelledPara>
<title>System difference code</title>
<para>The system difference code identifies major variants of a product. It consists of 1 thru 4 alphanumeric characters.</para>
<para>For example, if a bicycle is available in two different configurations, road or off-road, the system difference codes "A" and "B" could indicate which data modules apply to each configuration:</para>
<para>
<randomList>
<listItem>
<para>BIKE-A-00-00-00-00A-040A-D: contains information for the road variant.</para>
</listItem>
<listItem>
<para>BIKE-B-00-00-00-00A-040A-D: contains information for the off-road variant.</para>
</listItem>
</randomList>
</para>
</levelledPara>
<levelledPara>
<title>Standard numbering system</title>
<para>The standard numbering system identifies the detailed breakdown of the product. The idea derives from ATA100, where common components are given a specific chapter, section, subsection, and subject number across all publications. S1000D generalizes these as the system, subsystem, subsubsystem, and assembly codes. A number of common SNS are provided by the S1000D specification for any project to use, or a project can create its own SNS.</para>
<para>For example, the bicycle might be broken down as follows:</para>
<table frame="topbot" rowsep="0" colsep="0">
<title>Example SNS</title>
<tgroup cols="3">
<thead>
<row rowsep="1">
<entry>
<para>System</para>
</entry>
<entry>
<para>Subsystem</para>
</entry>
<entry>
<para>Name</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>D00</para>
</entry>
<entry>
<para>-00</para>
</entry>
<entry>
<para>Bicycle</para>
</entry>
</row>
<row>
<entry>
<para>DA0</para>
</entry>
<entry>
<para>-00</para>
</entry>
<entry>
<para>Wheels</para>
</entry>
</row>
<row>
<entry/>
<entry>
<para>-10</para>
</entry>
<entry>
<para>Front wheel</para>
</entry>
</row>
<row>
<entry/>
<entry>
<para>-20</para>
</entry>
<entry>
<para>Rear wheel</para>
</entry>
</row>
<row>
<entry>
<para>DA1</para>
</entry>
<entry>
<para>-00</para>
</entry>
<entry>
<para>Brakes</para>
</entry>
</row>
<row>
<entry/>
<entry>
<para>-10</para>
</entry>
<entry>
<para>Brake pads</para>
</entry>
</row>
<row>
<entry/>
<entry>
<para>-20</para>
</entry>
<entry>
<para>Front brake</para>
</entry>
</row>
<row>
<entry>
<para>DA2</para>
</entry>
<entry>
<para>-00</para>
</entry>
<entry>
<para>Steering system</para>
</entry>
</row>
<row>
<entry/>
<entry>
<para>-10</para>
</entry>
<entry>
<para>Stem</para>
</entry>
</row>
<row>
<entry/>
<entry>
<para>-20</para>
</entry>
<entry>
<para>Handlebar</para>
</entry>
</row>
<row>
<entry/>
<entry>
<para>-30</para>
</entry>
<entry>
<para>Headset</para>
</entry>
</row>
<row>
<entry>
<para>DA3</para>
</entry>
<entry>
<para>-00</para>
</entry>
<entry>
<para>Frame</para>
</entry>
</row>
<row>
<entry/>
<entry>
<para>-10</para>
</entry>
<entry>
<para>Horn</para>
</entry>
</row>
<row>
<entry>
<para>DA4</para>
</entry>
<entry>
<para>-00</para>
</entry>
<entry>
<para>Drivetrain</para>
</entry>
</row>
<row>
<entry/>
<entry>
<para>-10</para>
</entry>
<entry>
<para>Chain</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</levelledPara>
<levelledPara>
<title>Disassembly code</title>
<para>The disassembly code identifies further breakdown on an assembly to which maintenance information applies. The code consists of 2 typically numeric but optionally alphanumeric characters, plus a 1 thru 3 alphanumeric variant code. The variant code identifies minor variants in components, smaller than the major variants identified by the system difference code.</para>
<para>For example, two alternative physical parts that perform the same function (and thus have the same SNS in a functional breakdown) could be identified by disassembly code variants B and C respectively:
<randomList>
<listItem>
<para>BIKE-A-DA1-10-00-00B-720A-D: Installation procedures for brake pads produced by ABC company</para>
</listItem>
<listItem>
<para>BIKE-A-DA1-10-00-00C-720A-D: Installation procedures for brake pads produced by XYZ company</para>
</listItem>
</randomList>
</para>
</levelledPara>
<levelledPara>
<title>Information code</title>
<para>The information code identifies the kind of information contained within a data module. It consists of 3 alphanumeric characters, referred to as the primary, secondary, and tertiary codes. The S1000D specification defines a base set of information codes divided in to 11 primary categories:</para>
<para>
<randomList>
<listItem>
<para>000 - Function, data for plans and description</para>
</listItem>
<listItem>
<para>100 - Operation</para>
</listItem>
<listItem>
<para>200 - Servicing</para>
</listItem>
<listItem>
<para>300 - Examinations, tests and checks</para>
</listItem>
<listItem>
<para>400 - Fault reports and isolation procedures</para>
</listItem>
<listItem>
<para>500 - Disconnect, remove and disassembly procedures</para>
</listItem>
<listItem>
<para>600 - Repairs and locally make procedures and data</para>
</listItem>
<listItem>
<para>700 - Assemble, install and connect procedures</para>
</listItem>
<listItem>
<para>800 - Package, handling, storage and transportation</para>
</listItem>
<listItem>
<para>900 - Miscellaneous</para>
</listItem>
<listItem>
<para>C00 - Computer systems, software and data</para>
</listItem>
</randomList>
</para>
<para>The secondary code and tertiary codes break down these categories further in to more specific kinds of information. For example, 040 represents various kinds of descriptions, while 041 specifically deals with descriptions of how a component is made, and 042 specifically deals with the function of a component.</para>
<para>All purely numeric codes are reserved by the specification, but projects can create their own information codes using alphabetic characters for the tertiary code. For example, if a project wants to include a specific kind of description which does not fall under any of the available 040-049 codes, the project can allocate 04A-04Z. The project must then document the definitions for these information codes in their business rules. Projects may also translate the definitions of existing codes to better fit their project, as long as the original meaning is preserved.</para>
<para>The information code variant is a single alphanumeric character after the information code. This usually identifies alternative ways to perform procedures, with A being the default variant. For example, if 258A means "Other procedure to clean", 258B could mean "Other procedure to clean, Clean with water" and 258C could mean "Other procedure to clean, Clean with air". Both provide a way to clean a component, but in two alternative ways.</para>
</levelledPara>
<levelledPara>
<title>Item location code</title>
<para>The item location code identifies the context of the information contained in a data module, particularly where a task will be carried out. It is one of five codes:</para>
<para>
<randomList>
<listItem>
<para>A - the information is related to components installed in the system</para>
</listItem>
<listItem>
<para>B - the information is related to components installed in a component removed from the system</para>
</listItem>
<listItem>
<para>C - the information is related to components on the bench</para>
</listItem>
<listItem>
<para>D - the information is related to all three contexts above</para>
</listItem>
<listItem>
<para>T - the information is related to training</para>
</listItem>
</randomList>
</para>
</levelledPara>
</levelledPara>
<levelledPara>
<title>Data module title</title>
<para>The title of an S1000D data module is formed from two parts:</para>
<para>
<randomList>
<listItem>
<para>The technical name</para>
</listItem>
<listItem>
<para>The information name</para>
</listItem>
</randomList>
</para>
<para>The tech name is derived from the SNS of the data module, and the info name is derived from the short definition of the information code of the data module. For example, the data module BIKE-DA0-00-00-00A-040A-D, which has the SNS DA0-00-00 (Wheels) and information code 040 (Description), would be titled "Wheels - Description".</para>
</levelledPara>
<levelledPara>
<title>Data module content</title>
<para>S1000D provides a number of different schemas for different kinds of content within a data module. The schema dictates what elements can be used within that data module's contents. This limits the author of a data module to only using the appropriate elements for a particular context, and helps keep data consistent.</para>
<para>For example, the data module BIKE-DA0-20-00-00A-040A-D, which is titled "Rear wheel - Description" and will contain the description of the rear wheel of the bicycle, might use the <emphasis>descriptive</emphasis> schema. Another data module, BIKE-DA0-20-00-00A-520A-A, which is titled "Rear wheel - Remove procedure" and enumerates the steps to remove the rear wheel from the bicycle, might use the <emphasis>procedural</emphasis> schema.</para>
<para>Example of descriptive data module contents:</para>
<para>
<verbatimText verbatimStyle="vs11"><![CDATA[<levelledPara>
<title>General</title>
<para>A bicycle is a frame and a number of movable components with
mechanical parts that are completely open. There are no covers or
sheet metal panels that prevent access to the mechanical parts. Thus,
you can disassemble the different components of a bicycle to do:
<randomList>
<listItem>
<para>an inspection</para>
</listItem>
<listItem>
<para>a maintenance task</para>
</listItem>
<listItem>
<para>a repair task</para>
</listItem>
</randomList>
</para>
</levelledPara>]]></verbatimText>
</para>
<para>Example of procedural data module contents:</para>
<para>
<verbatimText verbatimStyle="vs11"><![CDATA[<proceduralStep>
<para>Hold the front of the bicycle.</para>
</proceduralStep>
<proceduralStep>
<para>Use the toolset to disengage the fork from the chainring by
pushing the wheel forwards and down.</para>
</proceduralStep>
<proceduralStep>
<para>Lift the wheel away from the frame.</para>
</proceduralStep>
<proceduralStep>
<para>Put the frame on the floor.</para>
</proceduralStep>]]></verbatimText>
</para>
</levelledPara>
</levelledPara>
</description>
</content>
</dmodule>
gopher://khzae.net/0/s1000d/s1kd-tools/src/doc/DMC-S1KDTOOLS-A-00-00-00-00A-018B-D_EN-CA.XML