S1000D® Issue 4.1 and Issue 4.2 Navigation Map

By Victoria Ichizli-Bartels

S1000D has become the preferred technical standard for complex technical publications because it offers comprehensive definitions for information captured in XML across the entire product life-cycle. It offers many options that satisfy the requirements of the defense and civil sectors, being implemented for products ranging from small hand-held devices to those that fly, float or move on land. 
The availability of these multiple options results in the Specification being considerably large and complex. The frequency with which S1000D is updated, along with the requirement to lower the cost of products in general (and technical publications specifically), have resulted in pressure to accelerate S1000D implementation. To do so, users of S1000D, new and seasoned, must, therefore, learn quickly, and be given access to requisite information regarding its implementation. 
Like its predecessor, this resource offers a unique approach to how information on the Specification is usually structured. It orders various Business Rules Decision Points (BRDP) defined in S1000D Issue 4.1 and Issue 4.2 into linear BRDP chains, to provide linear topic maps with clearly emerging associations and occurrences.
This resource can be used:
• To navigate the Specification while learning to work with it;
• To find references on your topic of interest;
• To navigate the Business Rules Decision Points Index in a logical order;
• As a first draft Table of Contents for an S1000D implementation map for your project or organization;
• As a checklist for your project or organization on what parts of S1000D to implement or not;
• To compile easily editable and sharable to-do lists to implement your project;
• As logic or algorithm to feed into a software tool and generate business rules documentation;
• And more.

• Language: English
• Publisher: Victoria Ichizli-Bartels
• Release date: May 3, 2017
• ISBN: 9781386918639

Book preview

S1000D® Issue 4.1 and Issue 4.2 Navigation Map

552+87 and 427+90 Business Rules Decision Points Arranged into two Linear Topic Maps to Facilitate Learning, Understanding, and Implementation of S1000D®

Victoria Ichizli-Bartels

S1000D® Issue 4.1 and Issue 4.2 Navigation Map

552+87 and 427+90 Business Rules Decision Points Arranged into two Linear Topic Maps to Facilitate Learning, Understanding, and Implementation of S1000D®

1st Edition

Copyright © 2017 Victoria Ichizli-Bartels

Contains parts of information from S1000D Issue 4.1 Untangled published by the author in 2016.

The moral right of the author has been asserted.

All rights reserved.

The author is not a lawyer. This book and the content provided herein are simply for guidance and educational purposes, and do not take the place of legal advice from your attorney. Every effort has been made to ensure that the content provided in this book is accurate and helpful. However, this is not an exhaustive resource on the subjects covered in this book. No liability is assumed for losses or damages due to the information provided. You are responsible for your own choices, actions, and results. You should consult your attorney for your specific project questions and needs.

No part of this publication may be reproduced, stored in or introduced into a retrieval system or transmitted, in any form or by any means (electronic, mechanical, photocopying, recording or otherwise), without the prior written permission of the author. The exceptions (as for example in relation to the use of the chain position numbers) are explicitly outlined in the text of this book.

Cover design by Victoria Ichizli-Bartels and Alice Jago

Cover image ©iStock.com

Photograph of Victoria Ichizli-Bartels by Click Aalborg

The S1000D™ and S1000D® are registered trademarks owned by ASD (AeroSpace and Defence Industries Association of Europe). They are mentioned in this book only for clarification and reference purposes. They are proprietary to ASD and are not affiliated with this document in any way.

Based on S1000D® Copyright (S1000D® Issue 4.1 and Issue 4.2) and Fair Use Doctrine (The Chicago Manual of Style, 16th Edition (4.77-4.87)) this book does not reproduce any part of the S1000D® Issue 4.1 and Issue 4.2, except quoting BRDP (Business Rules Decision Points) numbers and titles, and several explicitly quoted and referenced paragraphs from the specification (S1000D® Issue 4.1 and Issue 4.2) text. Chapter (Chap) and Paragraph (Para) numbers where the BRDP are defined in the specification text are quoted as well.

The definition for the Topic Maps is quoted from www.topicmaps.org.

optimistwriter.com

For those who started S1000D®.

Thank you for initiating such an exciting environment for a happy nerd.

Preface

Less than a year ago, I published S1000D Issue 4.1 Untangled: 552+ Business Rules Decision Points Arranged into a Linear Topic Map to Facilitate Learning, Understanding and Implementation of S1000D. It received very positive feedback from the S1000D community and I was immediately asked if I planned to write more, both extending the information for S1000D Issue 4.1, and to include the latest Issue 4.2.

After some contemplation, due to the relationship between the two Issues of the specification — having both backward and forward compatibility — I decided to satisfy these requests with a new resource.

This book is the result.

I hope that, as with the first one, this resource will support those implementing S1000D in their work, as well as S1000D working groups in further developing the specification. As an integral member, I will continue to contribute the knowledge I have gathered during the creation of these resources to the S1000D community.

Victoria Ichizli-Bartels,

Aalborg 2017

Preface to S1000D Issue 4.1 Untangled

Many times during my ten-year chairmanship of the S1000D Implementation Guide and Business Rules Task Teams, which later became the Business Rules Working Group, I was asked when I would write a S1000D for Dummies.

I was intrigued by this idea, so I scrutinized a number of classical and new books For Dummies and bought various books on XML and SGML (one of which even has Implementation Guide in its title), but still I could not find a way to approach this challenge.

Then I forgot all about the book for dummies, remembering it from time to time and then forgetting again.

Fast forward to today, where you find a seemingly strange book in front of you.

It is not a book for dummies. It is neither an index, nor an introductory course guide to S1000D. And it is not a classic topic map. Instead, it is a linear thread of decision points that need to be addressed when implementing this particular technical specification.

And you can also use it as a learning resource; as a map for figuring out which topics you need to concentrate on and which you can ignore while implementing S1000D.

I see this resource as a versatile and powerful tool, especially because it neither reinvents nor interprets what is available on S1000D. It complements the current chapter structure offered by S1000D and together with it provides a great navigation portfolio for successful and much faster implementation of this multidimensional, global, and still quite precise and clear technical standard.

You can also see this resource as a workbook, especially the paperback version of it, where you can make notes related to your project or organization.

I hope you will find it as useful and helpful as I discovered it to be, while developing it. At some stage in this work, this chain of Business Rules Decision Points, the linear topic map started evolving on its own and taking shape. And only when those topics emerged did I understand what it was. A topic map with concrete associations and visible, logical occurrences. You can find more on this in the subsequent chapters of this book.

I wish you success and fun while learning, understanding and implementing S1000D!

Victoria Ichizli-Bartels

Introduction

(Enhanced and Updated from S1000D Issue 4.1 Untangled)

S1000D®

S1000D® (International specification for technical publications using a common source database) has become the preferred technical standard for sophisticated technical publications. It is utilized globally, both geographically and across the landscape of products and industries. Both the defense and civil sectors widely implement it for products ranging from small hand-held devices to those that fly, float or move on land.

Here is how S1000D is defined in Issue 4.1 and Issue 4.2 (and also in most of the other Issues, i.e. versions):

S1000D is an international specification for the procurement and production of technical publications. While the title restricts its use to technical publications, it has been found through application that the principles of the specification can be applied to non-technical publications. (S1000D Issue 4.1 and Issue 4.2, Chap 1.1, Para 2)

Short, clear and easily understandable. These characteristics apply to all the information it contains.

Of course, the text of S1000D is written by humans and therefore contains some errors and conflicting definitions, which are removed and corrected in subsequent Issues. But in general, it can be said that if you need to know how to design, generate, maintain, exchange, discard, or perform some other action, within the life-cycle of a technical (or non-technical) document coded with Extensible Markup Language (XML), you will find the answer in the specification.

You can also join the S1000D community as an active member and suggest an addition or correction to its Schemas, to the specification text, or other objects the S1000D Steering Committee and working groups provide and maintain. Then your change proposal will be examined, along with others, and considered whether it adds something new and is needed or whether it redefines existing concepts and constructs. You might even find yourself engulfed in S1000D Heavy E-Mail Traffic (SHET, an official S1000D abbreviation) with many suggestions and examples of how to achieve what you are looking for using the elements and attributes already available in many of the S1000D Schemas.

Most probably you would agree that the redefinition and reinterpretation of existing constructs would only make the substantial tome of more than three thousand five hundred pages unnecessarily heavier, both to hold and to understand.

Many people in the S1000D community would sympathize if you felt uneasy, or even terrified, when your manager said, Download the S1000D Issue (put here the one you’ve been told to work with). Report to me in one month on what it is about and what we have to do to implement it.

Evidently, S1000D and other standards and specifications are written to be applied, and not to be read for pleasure. Thus, all its readers and users look for hints and key concepts to determine what they need to decide and consider, before beginning the process of implementation.

Major technical concepts and constructs were defined from the very first (Initial) Issue of S1000D back in the 1990s, but only since Issue 4.1 was published in 2012 could you open the specification and find a list of points you needed to address to implement it — those where you have to make individual decisions about the options offered by the standard. But again, just like the volume of the specification, the sheer number of these decision points will appear daunting.

Business Rules

There has been a certain reluctance towards Business Rules in the past couple of years. One possible reason is that many topics considered within the S1000D community are brought up, discussed and implemented within one publication cycle of an S1000D Issue. The Business Rules question has been there for many Issues without being completely resolved.

There is also a controversy about Business Rules. Some members of the community say, We’ve talked enough about business rules, now we need to do the work and implement the specification. Some others say, Yeah, standardizing business rules is necessary, but I have more urgent concepts to develop and bring into S1000D.

And then there are members of the Business Rules Working Group who say, We have to figure out a good, clear and stable method of defining Business Rules, and provide excellent guidance on how to implement S1000D in the most effective and efficient ways.

This group of people has come up with the following definition for Business Rules:

Business rules are decisions that are made by a project or an organization on how to implement S1000D. Business rules cover all aspects of S1000D and are not limited to authoring or illustrating. They can also address issues that are not defined in S1000D such as rules related to how S1000D interfaces with other standards, specifications and business processes that are related to its implementation. (S1000D Issue 4.1 and Issue 4.2, Chap 2.5, Para 2.1)

And since any step made to implement a standard needs a decision and commitment to that decision, then business rules are simply the vital thread for the success of a product or service in general, and technical publications in particular, when it comes to S1000D.

Business Rules Decision Points (BRDP)

The S1000D defines five hundred and fifty-two (552) Business Rules Decision Points (BRDP) in Issue 4.1, and four hundred twenty-nine (429) in Issue 4.2. On top of that, S1000D users can define additional decision points for their projects and organizations, and there are decision points that require many sub-decisions to be made before you can call the given task complete. One particular decision point requires several hundred other decisions to be made. Here it is:

"Business rule decision point BRDP-S1-00007 – Use of optional elements and attributes:

– Decide whether and how to use each optional element and attribute in its structural context." (S1000D Issue 4.1 and Issue 4.2, Chap 2.5.1, Para 2.1.3)

S1000D Issue 4.1 and Issue 4.2 define twenty-six (26) and twenty-eight (28) XML Schemas respectively. Each Schema contains tens of optional elements and attributes. Even if a project should choose to apply only a very limited number of Schemas, such as, for example, the descriptive data module, publication module and the data dispatch note, the business rules designers will have to make decisions on more than fifty elements and at least as many attributes. On top of that, some of the elements and attributes will have global values, true for all types of data, and some of them will differ with the context of their use. For example, change attributes might be allowed on some elements, like

but forbidden on its child element . And this decision might vary for different types of illustrations. Illustrations in the Illustrated Parts Data (IPD) data modules often receive special treatment that differs from the illustrations used in other data module types.

In the production of technical publications, all these aspects need to be properly evaluated, and conscious and appropriate decisions then made, recorded and maintained.

Functional Logic Behind the Chapter Structure of S1000D

Since Issue 2.0, S1000D comprises a functional breakdown. This structure is clearly visible from the titles of its main chapters (Chap):

Chap 3 Information generation

Chap 4 Information management

Chap 6 Information presentation and use

Chap 7 Information processing.

The exceptions to this are introductory chapters 1 and 2, concluding chapters 8 and 9 (which document the meaning of various abbreviations, terms, and codes), and Chap 5 Information sets and publications.

Structuring the specification in such a functional manner is extremely practical because this structure targets the specific roles within the life-cycle of the technical documentation process. Managers will often consult Chap 4, while technical authors and illustration designers will often open Chap 3, especially the sub-chapter 3.9 Information generation - Authoring. Developers of software aimed at supporting S1000D compliant processes will often look at Chap 7, which directs them to relevant parts of other chapters.

The challenge comes when you want to find information in the specification on a certain topic, or clarify what decisions you need to make to implement a concept of S1000D. For example, if you would like to implement Service Bulletins, then you will need to read Chap 3.9.5.2.15 and its sub-chapters, Chap 5.2.1.16, as well as some other chapters with related information.

Helpfully, S1000D Issue 4.1 provides a Subject Index in Chap 9.2.3, where you can refer to the chapters containing the information you are looking for. However, it is not possible to identify connections between various subjects within the Index, because, as with most subject indexes, it is in alphabetical order.

The book S1000D Issue 4.1 Untangled offered a novel approach to structuring the information available in the specification. It ordered different BRDP, and the corresponding context information provided by S1000D, into a linear BRDP chain or a linear topic map, with BRDP groups revealing various topics addressed inside the S1000D text.

Back-story, Experience of Working with, and Feedback on S1000D Issue 4.1 Untangled

The story of the book S1000D Issue 4.1 Untangled goes back several years.

One of the most active members the Business Rules Working Group (BRWG) has ever known, Corinne (Corky) Rockweiler submitted a Change Proposal Form (CPF) in 2009 requesting that the relationships between various Business Rules Decision Points (BRDP) inside the S1000D be investigated and established. All members of the BRWG, as well as the Steering Committee, agreed that this was an essential task.

And so, the BRWG set out to determine what these relationships were. I remember starting and not finishing several mind maps, and ending up with a massively complex structure without any order, and that made no sense whatsoever. The members of the BRWG also had various opinions, varying over time, as to how the same decision point related to all the others.

After a multitude, of discussions we gradually realized that we were a long way from finding precise relationships between the BRDP, but we saw increasingly clearly the relationship of the BRDP to various concepts and constructs defined in the specification.

First, of course, was their relationship to the text of the specification. Fortunately, this was straightforward to do and could be determined immediately. In fact, in defining the BRDP Index for S1000D Issue 4.1, there was only a one-to-one relationship. Each BRDP had a distinct position inside the specification text, and there was no intention to define it in more than one place.

The next step we made was to map the BRDP in respect to the business rules categories defined in Chap 2.5.1. We discovered that the same BRDP could be attributed to more than one category.

Then, since some of the chapters of the specification concentrated on individual data module types, and therefore Schemas, we investigated how the BRDP related to Schemas. The third map emerged.

We did the same exercise for configurable attributes since they add color to various contexts of the specification as well.

We embedded all this information into one Excel file, enhanced it with maps of optional and mandatory elements and attributes for each S1000D Schema (created by the Schema-Man, the absolute Schema master and guardian of the S1000D Schemas for many years, Nicolas (Nico) Dupuy). Then, we added the full list of Schemas, started a spreadsheet containing the actual values for each business rules decision point (also initiated by Nico), and added an introduction.

After a presentation introducing this information to the S1000D community at the S1000D User Forum in San Antonio in the Summer of 2014, the BR relationships Excel file with the name BRDP-relationships-Iss4-1_001-00.xlsx was included in the Issue 4.1 download package available for the whole community to use.

By that time, we had given up trying to find a way to model relationships between the various business rules decision points, realizing that opinions on how such a map should look would differ from one S1000D user to another, and between the projects it would be used on.

In the meantime, I became a professional writer, eagerly absorbing everything I could that piqued my curiosity on the craft of writing. I learned much about writing, and began applying these tips to my practice. Two in particular became guiding flags in almost every project I had to approach, including S1000D related work.

The first one is:

You can’t edit an empty page.

Yet that is basically what many working groups do, including the BRWG. They brainstorm and discuss. Which is, of course, not a bad thing in itself, but the problem was we were discussing something that didn’t exist yet. We were trying to find a common approach to business rules, without already having one in our hands to edit and critique. The world was full of various implementation strategies, but they were proprietary and could not serve as a template for a standard approach. And I, as Chair of the group, failed to see this at the time.

The second piece of writing wisdom I am inspired by is:

"There are many perfect ways to write the same book."

Elizabeth Gilbert, author of Eat, Pray, Love, wrote the following about a ten-page short story she had to shorten by thirty per cent:

The new version was neither better nor worse than the old version; it was just profoundly different. Elizabeth Gilbert, Big Magic: Creative Living Beyond Fear

The same is true of most S1000D implementations. They can’t be compared because they are profoundly different.

By now I had absorbed these and other writing pearls of wisdom from such masters as Stephen King, Natalie Goldberg, Anne Lamott, James Scott Bell, and many others. I also had the tried and tested What if? tool at my disposal. So, I started wondering what would happen if I devised a method of approaching business rules. I was curious to determine which BRDP a project should decide on first when implementing S1000D, and when that had been decided on which next, and so on until all BRDP had been considered.

Initially, this BRDP index project started as a blog series back in 2015, and over time I started grouping the decision points into topics, such as those you would consider while setting up the Common Source Data Base (CSDB), for example. I regularly reported the results to the Business Rules Working Group and asked for their feedback, which was invaluable.

I published the book S1000D Issue 4.1 Untangled in July 2016. I couldn’t have foreseen what the feedback would be, I just hoped that it would be a helpful resource.

I took the book to the S1000D User Forum in Seville in September of the same year, and when the participants clapped eyes on it they brightened in approval. I was surprised but happy when almost immediately I was asked if I planned to compile and publish similar works, extending it to future and even previous Issues of S1000D. I was immensely happy when during lunch, as we discussed the idea behind S1000D Issue 4.1 Untangled, one of my teachers and role models, Peter Zimmermann, exclaimed, I always said we should go this way!

The book sold around fifty copies in less than a year, which is remarkable when you consider that there are several hundred S1000D projects in the world (while only a part of these applies the Issue 4.1), and it is usual for colleagues in a department or project to share technical literature. To this day I receive lots of agreement that such a grouping is useful and makes sense.

The following five-star review on Amazon was also extremely encouraging: This book is going to be a great resource! There are very few resources that deal with S1000D and this one looks to be the clear winner. The language is clear, easy to read, and very helpful. It is written in a way that is informative and easy to follow. The locations of the business rules to where they are found are helpful as well. I very much enjoy the OW’s words of wisdom. These are insights that, for someone new to S1000D, might be invaluable tips. I have learned much from this book and will most likely refer to it over and over.

Finally, I have tested S1000D Issue 4.1 Untangled myself by reworking and customizing the resource for a customer applying S1000D Issue 4.0.1 to their project. In this project I moved some of the BRDP from one group to another, switched the positions of the BRDP groups, added BRDP present in Issue 4.0.1 but missing in Issue 4.1 (due to the BRDP clean-up undertaken on that Issue), and of course also deleted the irrelevant ones. But in general, the sequence of topics and the BRDP within topics largely remained the same and helped in defining the business rules. The grouping of BRDP into topics also enabled reference to and double checking of business rules decisions made previously. Navigation of the customer’s business rules document became much faster and smoother. The grouping into topics helped to avoid ambiguous decisions on redundant BRDP, which were still present to a large extent in Issue 4.0.1.

Although I didn’t expect it to resonate with users to such an extent, or to use the book so much in my own work, I must admit that I had hoped the book would be useful. Thus, with this wish having been fulfilled, the decision to create a follow-up resource came naturally.

Linear Topic Map Approach to Structuring Information Provided by S1000D

The topic map structure emerged by arranging the Business Rules Decision Points in definition order. The sequential order can vary between projects and organizations, but this method of ordering them will be recognized by many organizations that implement S1000D. It can also be viewed as a linear chain of steps, some of which are less small steps than jumps to the next topic.

The Business Rules Decision Points Groups that emerged from this exercise can be clearly attributed to the various topics addressed by S1000D. Their positions in this so-called BRDP chain and their manifestation within the technical documentation life-cycle process provide associations between them. Through the direct relation between each BRDP and its location within the specification text, the BRDP groups / S1000D topics can be attributed to chapters and paragraphs, that is to their occurrences inside specification.

With topics, associations, and occurrences in place, we have the definition of a topic map. Topics Maps is the only ISO standard (ISO 13250) among various mapping approaches, including concept and mind mapping. The linear feature of this topic map, makes it, together with all its components — topics, associations, and occurrences — an extremely user-friendly way to learn, understand and implement S1000D, quickly and efficiently.

As with concept and mind maps, as well as any other topic map, the topics of this S1000D BRDP map can be defined in various ways. S1000D Issue 4.1 Untangled offered the first linear topic map approach to S1000D to be published.

Topic Maps is an international industry standard (ISO 13250) for information management and interchange. The Topic Maps Data Model is the heart of the Topic Maps standards and is supported by several file formats, query languages and modeling languages. A topic map in a software system is usually managed using a Topic Maps engine. (www.topicmaps.org)

The BRDP chain, or S1000D topic map, defined for the first time in S1000D Issue 4.1 Untangled has been further developed and enhanced in this book. The definition of the BRDP chains for Issue 4.1 and Issue 4.2 is preceded by two introductory chapters, one of which specifies the abbreviations, conventions, and practices applied here, and the other listing possible ways for this resource to be used.

Abbreviations, Conventions, and Practices

(Enhanced and Updated from S1000D Issue 4.1 Untangled)

Frequently Used Abbreviations and Pointers

BR — Business Rule

BRDP — Business Rules Decision Point(s)

BRWG —Business Rules Working Group

Chap — Chapter

OW — Optimist Writer (the author of this book)

Para — Paragraph

Note: Refer to Chap 9.2.2 in S1000D Issue 4.1 and Issue 4.2 for the abbreviations and acronyms used in the quoted specification text.

Conventions and Practices

In this book, each BRDP is considered from various angles for both S1000D Issue 4.1 and Issue 4.2. These aspects are reflected in the entries for each BRDP. These are defined as follows.

BRDP Group or S1000D Issue 4.1 / Issue 4.2 Topic: This is a group of Business Rules Decision Points resulting in a meaningful and self-contained topic, such as data module coding, applicability, CAGE codes, etc. Using a more figurative language, moving from BRDP to a BRDP inside a group is a logical next step, while moving from the last step of one group to the first step of the next group is a bigger jump and change of subject.

Chain Position Number: A chain position number indicates where in the BRDP chain the given Business Rule Decision Point is situated, and which BRDP precede and succeed the given one. For example, in (Iss41_S1-00070_S1-00071_S1-00373_inside), the BRDP-S1-00071 is the Business Rule Decision Point under consideration. In the BRDP chains defined in this book for Issue 4.1 and Issue 4.2, this decision point is preceded by BRDP-S1-00070 and followed by BRDP-S1-00373. The prefixes Iss41 and Iss42 show which of the two Issues is considered in the given entry: Issue 4.1 or Issue 4.2. The letters BRDP — indicating in the specification that the given code is a unique number for a Business Rules Decision Point — have been dropped inside the chain position number for the sake of shortness and readability. The first and the last BRDP in the chain contain the capitalized words START and END, indicating the beginning and the end of the BRDP chain, correspondingly. Each chain position number also includes one of the words: single, start, end, or inside. These words show where the BRDP under consideration is situated in the given BRDP group / S1000D topic. Using the example above, BRDP-S1-00071 has its place inside its BRDP group. The word single indicates that the given BRDP is alone without any neighbors inside its BRDP group / S1000D topic.

Number and Title: For BRDP starting with BRDP-S1-, Number and Title quote the number and title of the BRDP defined by S1000D. Most of those starting with BRDP-OW- were identified in S1000D Issue 4.1 Untangled for the first time. Three more of these were added here in this book. All these additional decision points were given at the points where there were obvious (from my point of view) gaps in the BRDP groups or between them.

Location in S1000D Issue 4.1 or Issue 4.2: These pointers go to the numbers of the chapter (Chap) and the paragraph (Para) inside the specification text. This entry is new and didn’t exist in S1000D Issue 4.1 Untangled. See more details on this in the next chapter How to Use This Book, its section Some Details for the Suggested Usage Scenarios, and the sub-section Finding references on your topic of interest.

Relationship between the BRDP definitions in S1000D Issue 4.1 and Issue 4.2: The relationship of BRDP defined in the Issue 4.1 BRDP chain