S1000D For Beginners

원문: https://medium.com/s1000d/s1000d-for-beginners-9a90fea311e7

 

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.

이 글은 기술적인 writer와 illustrator를 위한 가이드이다. 기술적인 글쓰기의 세계는 시작, 중간, 마지막의 선형적인 글쓰기의 개념에서 변화하고 있다. 필요한 정확한 정보를, 당신이 처한 상황에 가장 적확한 형태로 정확히 가지고 있다는 개념으로 나아가고 있다. 

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

이러한 미션을 주도하는 단체가 국제 표준 기구 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.
S1000D는 기술 문서의 조달 및 생산을 위한 국제 사양이다. 텍스트 및 삽화의 버전을 준비하고 관리하기 위한 사양이다. S1000D.org 는 정보 교환을 위한 표준을 수립했다. 다음은 S1000D 규정 준수를 위한 기술적인 방식의  기본 개요이다.

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.

이 책의 목적은 S1000D 기술 출판 표준에 따라 문서를 전달하고자 하는 기술적인 작가와 일러스트레이터를 위한 가이드를 제공하는 것이다.

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.

대부분의 기술 작가는 기술 문서를 작성하기 위해 MicroSoft Word나 유사한 application을 사용한다. 그러나, 기술 문서는 겉으로 보이는 것 이상이 있는 cloud database로 이동하고 있다.

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.

유라거 수년간 사용해 온 표준 응용 프로그램은 디지털 시대의 요구사항에 적합하지 않다. Microsoft Word 및 기타 프로그램으로는 작업을 쉽게 완료할 수 없다.

What is required now is digestible meta data. Searchable connected information and the international standards organization S1000D has defined those data standards.

지금 요구되는 것은 이해하기 쉬운 meta data이다. 검색 가능한 연결 정보와 국제 표준 기구 S1000D가 이러한 data 표준을 정의했다.

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.

그것은 누구나 해당 표준을 사용할 수 있는 “open source” 이다. 특정 SW application을 필요로 하지 않으므로, S1000D의 규칙을 준수하는 한, 이론적으로 메모장(notepad)에서 간단하게 text를 생성하면 된다. 그리고, 기본 규칙은 data가 .xml 형식이어야 한다는 점이다.

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.

XML은 1960년대부터 사용된 프로그래밍 코드이다. XML은 eXtensible Markup Language의 약자이다. 프로그래밍 코드는 daya를 저장하고 전송하도록 설계되었다. XML은 처음부처 사람과 기계가 모두 읽을 수 있도록 설계되었다.

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은 markup을 통해 문서를 전자적으로 인코딩하는 규칙의 집합이다. 그것의 주요 목적은 서로 다른 정보 시스템간에 data 공유를 쉽게 하기 위함이다. W3C(the World Wide Web Consortium)의 산출물이다.

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).

XML은 누구나 문서를 작성하는데 사용할 수 있는 기반을 제공한다. 소유권이 없고 누구의 소유도 아니다. 모든 이에게 개방적이고 사용가능한 시스템을 유지하는 국제 회원 컨소시엄이 있다. XML은 전세계적으로 사용된다. 웹사이트를 구축하는데 사용된 최초의 도구 중 하나였는데, 그것이 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.

S1000D는 특히 기술 문서를 위한 XML의 표준을 정의한다. 그리고, S1000D의 특징 중 하나는 기술 출판물 제작에 개방형 시스템(open systems) 방식의 접근을 사용한다는 점이다. 특정 도두나 어플리케이션을 요구하지 않는다.

XML is used by a variety of industries. Some interesting ones are Golfing: GolfML, Aerospace:Spacecraft Markup Language, Music: Music Markup Language, Advertis­ing: AdXML, Artificial Intelligence: AIML and fiction eBooks: FictionBook.

XML은 다양한 산업에서 사용된다. 흥미로운 것들로는 Golfing: GolfML, Aerospace:Spacecraft Markup Language, Music: Music Markup Language, Advertis­ing: 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.

XML을 매우 인기있게 만든 것은 어떤 산업에 대해서도 iPads, iPhones, internet web browsers, laptops 으로 export될 수 있고, 적응이 가능하기 때문이다.

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.

음악을 예로 들면, Music.XML은 Finale, Sibelius, MuseScore을 포함한 악보 작성 프로그램에서 지원된다. Music.XML은 악보를 인식하는 OCR(optical character recognition)을 가지고 있다. 대부분의 음악 시퀀서(MIDI, 작곡) 프로그램은 올바른 음악 시퀀스를 얻기 위하여 XML code를 사용한다. 이것이 디지털 음악이 제어되는 방식이다. 또 음악을 "code"하는데 사용된다. 그들은 “acoustic”, “classical”, “jazz” 같은 단어를 할당한다. 검색 엔진에 넣으면, Wes Montgomery, Django Reinhardt, 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 doc­uments 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는 “open source” 시스템과 tool 독립적인 XML을 사용한다. 그리고, 분산 시스템 전반에 걸쳐 document와 process 구현에 필요한 구조를 제공한다. 특정 회사에 소유될 필요없이 강력하다. 그것은 최종 사용자를 위한 정보의 혼용성이라는 유사한 목표를 염두에 두고 있는 사람들의 컨소시엄에 의해 관리된다.

S1000D is the resource for technical authors and illustrations. It is an XML specifi­cation for the procurement and production of technical manuals. The specification is freely available for any industry to utilize and available from public.s1000D.org.

S1000D는 기술 작가 및 삽화가를 위한 리소스이다. 기술 매뉴얼의 조달 및 생산을 위한 XML 규격이다. 이 규격은 모든 업계가 자유로이 사용될 수 있고 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.

S1000D 운영 위원회는 많은 참여 기관으로 구성되어 있다. 유럽 항공 우주 방위 산업 협회, 통합 물류 지원을 위한 국제 표준 기구, 미국 항공 및 기타 기관이 있다.

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.

그리고, 모든 문서는 S1000D용 XML 형식으로 전달되어야 한다. 먼저, XML에 대하여 이야기하기 전에 인쇄된 복사본과 PDF의 오래된 기본 용어 및 정의가 어떻게 바뀌었는지 이해해야 한다.

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).

Word를 사용한 것을 우리는 "document"라 불렀다. 잘 살펴보면, Word application을 사용한 것에 대해 과거 시제를 사용했다는 것을 알 수 있을 것이다. 간체화된 기술 영어(Simplified Technical English)를 따르는 이들을 위해 현재 시제를 사용한다. 전자 출판(epub)의 세계에서, "document"를 만들지 않는다. Data Module(DM)을 만든다.

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.

그것들은 data에 대한 모든 것이기 때문에 “Data Modules”이라 한다. 텍스트, 그림, 날짜, 부품 번호, 경고, 주의 메모. 이 모두는 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.

과거에는 이것이 document name이었다. S1000D에서 그것은 기술 매뉴얼 식별 번호(TMIN)이다. 시별 번호는 특정 형식이 있다. TMIN의 명명 규칙에 대해서는 자세히 설명하겠지만, 몇 가지 예를 들어 보겠다.

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.

S1000D는 독자와 장비 SW 프로그램 어플리케이션 모두에서 텍스트와 그림을 모두 소화/전송/이해 가능하도록 만들었다. 

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.

출판의 기준은 “text” 와 “markup language” 그 이상이다. S1000D는 data에 대한 모든 것이다. 전체 data set: 유지보수, 고객 서비스, 배송 및 수령, 일러스트레이션, 부품, 작동 매뉴얼 및 엔지니어링 도면. 이 모든 것이 디지털 형식으로 함께 연결되었다. 기술 작성자는 data를 유용한 정보로 편집한다. data를 쉽게 사용할 수 없다면, data가 있어도 문슨 소용인가? 다른 시스템에 다시 입력할 필요가 없는 유용한 정보를 상상해 보자. 이것은 "PDF 파일"이나 모든 데이터가 포함된 USB를 받는 것보다 훨씬 더 낫다.

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?

이 책은 기술작가와 삽화가에게 S1000D에 대한 일반적은 작업 지식을 제공하기 위해 작성되었다. 여기에서는 이전의 MicroSoft Word application을 사용하여 매뉴얼을 만드는 것처럼, S1000D 요구사항을 제시한다. 결국, 본질적으로 동일한 정보라면 얼마나 다를까?

As different as night and day.

완전히 다르다.

Headers

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

Word에서는 “Page Headers” 라 한다. PDF에서는 “Running Heads” 라 한다. 그러나 e-book 용 SW 프로그램 중 일부는 “Viewer Bars” 라는 용어를 사용한다.

Notice the Page Headers include the “security classification”.

Page Header는 “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.

TMIN은 기본적으로 document의 file name이다. 이것은 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.

S1000D는 Page Footers에 최대 3개의 data를 포함할 수 있다. 최대 3개 더 이상은 없다.

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), 개정사항(revisions), 삭제된 text, 복원된 내용으로 출판물을 업데이트하고 발간하는 과정을 가지고 있다. 출판물을 업데이트하고 발표하는 빈도는 프로젝트별로 결정된다.

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

변경사항(changes)은 변경된 내용 옆에 게시된 큰 4.5 point 검은색 막대인 “Change Bars” 를 사용하도록 지정되었다.

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.

변경 사유는 identification(식별), status(상태) section에 요약되어 기록된다. change bar의 임계값이 50% 이상이 되어 읽기 어려운지 여부에 대해 토론한 다음에, 전체 페이지가 “revised”(개정) 되었다고 footer(바닥글)을 표시하고, 변경 표시줄을 제거했다.

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).

S1000D의 경우, 편집 변경 사항을 제외한 모든 변경 사항을 표시하고 업데이트 이유를 제공해야 한다. 업데이트 이유 텍스트는 기술 매뉴얼(TM)에 대한 Revision Summary(개정 요약)를 자동으로 생성하는데 사용된다.

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)은 번호가 002 이상인 issue에 대해서먼 표사할 수 있다는 것이 대단히 합리적이다. S1000D에는 많은 규칙이 있다. 이것은 시작에 불과하다.

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.

문서를 변경하려면 “elements” 를 사용해야 한다. change element는 <reasonForUpdate> 이다. 해당 element에 대한 attribute 나 choice 는 ‘changeMark’, ‘changeType’, ‘reaonForUpdateRefIDs’ 이다. 자세한 사항은 나중에 ...

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

The international standards group created a bike example for S1000D.

PMC-S1000DBIKE-C3002-LOAP1-00_000-02_EN-US.pdf

15.20MB

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 $par­ent 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

 

The S1000D Standard Specification

 

The 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 specifica­tions 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 out­line”. 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 tech­nical 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

 

S1000D 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 techni­cal 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 devel­oped 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 accom­pany the data modules, but we will save that topic for later. The following table pres­ent the types of data modules and a description of each of them.

 

Data Modules and Descriptions

 

Data Module Contents and Meta Data

Each 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 docu­mentation 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 mod­ule. 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 con­tains the following information:

MODEL

The Model is the model or overall to which the technical data is applica­ble. 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 pres­ents several different codes which might be useful

 

Systems and Subsystem Codes and Definitions

SYSTEM DIFFERENCE CODE

The System Difference Code indicates there are alternative versions of the system and subsystem without affecting the type, model or variant identity. The Sys­tem 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 sys­tem 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)

The 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 Sys­tem (SNS) also created the S1000D system. Typical standard breakdown of compo­nents 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 recircula­tion. 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 infor­mation 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 hier­archy of three pairs of numbers. The following table presents a examples for SNS codes for the aircraft business.

 

Standard Numbering System (SNS)

DISASSEMBLY CODE

The 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

Used 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

The function code describes which type of directions are pro­vided. 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 disassem­ble something. The following table provides a sample of the most often used pri­mary function codes. The entire set of function codes is literally pages and pages of selection available.

Function Codes for Task Descriptions

FUNCTION CODE VARIANT

The Function Code Variant is a one Letter assign­ment. 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 spe­cific task instructions.

ITEM LOCATION

Item Location code identifies the location of the unit on which mainte­nance 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 struc­ture 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 dis­play 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 pro­vides a means to store data in plain text format. This provides a software and hard­ware 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 applica­tions 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 con­tains 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 enter­ing 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 man­datory (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 man­datory.

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 pur­chase 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 sepa­rate file folder for “illustrations”.

Common Source Data Base (CSDB)

Because there are so many pieces of the XML puzzle that combine to make a docu­ment, 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 Pub­lication 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_Con­sortium.

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 cre­ate 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 pur­pose 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 infor­mation 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”, “Illus­trated 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 con­tainer 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 attri­butes 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 disassem­bly 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 Pub­lishing 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 plan­ning 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 mil­itary specification MIL-STD-40051 is the perparation of Digital Technical Inforam­tion 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 procure­ment 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 pro­cesses. 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 pro­vides 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 struc­ture. There are entire books written regarding how to implement the various pars­ers. 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 docu­ment 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 documenta­tion 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 Micro­Soft Word to a structured framework is work efficiency. There is a simple miscon­ception 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 pub­lishing 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 environ­ment 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 struc­ture 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 for­matting 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 con­trol 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 publica­tions with changes, revisions, deleted text, reinstated stuff. The frequency of updat­ing 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 unmanage­able.

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 rec­ommended specifications for the content, structure and deliverables to meet the communication requirements, those being the physical, electronic and future tech­nologyof 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-cen­tered source of information creates a modular, bite size information. The informa­tion 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 infor­mation 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 where 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 <identAndStatus­Section>.

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 identifi­cation 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.- extension­Code (M), the data module extended code. The value is decided by the data module producer.

dmCode

is the basic identify code parameters.

 

Chapter 8 Illustrations

 

Chapter 9 Applicability

 

Chapter 10 Let’s Do This

 

Chapter 11 Common Information Repositories

 

FAQ