Principles of Rapid Response

This article describes the concepts of a rapid response operational model. Analysis of mission objectives enable coordinated application of pre-staged resources for adaptive actions in a dynamic situation. This relies on an organization that supports continuous training for tools, techniques and libraries of modular resources that can be quickly integrated and scheduled in accordance with the mission analysis. The key is a bottom to top commitment by members of the organzation to the principles and practices of rapid response.

It is vital that the organization leaders work with their teams daily in close quarters to create a rapid response culture. To quote an old saying, "Love from afar is for fools and cuckholds."

Create A Culture of Rapid Response

A rapid response culture:

• Serves customers whose principles of effective rapid response are also realized through developing best practices in the face of dynamically evolving challenges. This quality is often referred to as resilience.
• Finds and supports the best people who embrace innovation and retains only those who accept the demands to be ready and able to respond rapidly with assurance of quality and completeness within the constraints of the customer's operational needs.
• Improves production bandwidth among teams that organize and create resources for maximum reuse and reapplication. The critical factor is in-depth understanding of the tools and how they can be applied nimbly given mission planning, requirements and constraints.
• Leverages experience. Processes are best managed by the people doing the work when they are trained to understand deliverables and tools at the highest level of professional competence.
• Emphasizes planning and local adaptibility. Operations are managed and measured to ensure every asset is prepared, resourced and capable but rely on local management of a dynamic environment.
• Demands situational awareness. Situational awareness is a fundamental idea for resilient response. The local team must have access to and the competence to adjust a plan as the situation changes and new opportunities to respond effectively are realized.
• Captures, tests and shares opportunities to improve and enhance team performance in a real-time production environment. Idea hoarding is not rewarded.
• Trains as a team to improve organizational technical competence and ensure responses are both mission-oriented and forward-looking

Training, staged resources and effective open communication are the must-haves for organizations and individuals who anticipate needs and respond rapidly with high quality results.

Do Not Accept Mediocrity

These are three common mistakes organizations make with regard to achieving rapid response goals:

1. It is risky to design a production system based on the requirements of a single project unless there are no other business objectives for the system.
2. Emphasis on brute force to get a job done on schedule may be unavoidable given current conditions but to accept or institutionalize that approach will permanently damage the corporate culture and inevitably lose business to smarter competitors. Brute force does not scale. You need force multipliers.
3. What people do often becomes habit and relying on habit over commitment to innovation and shared ideas is certain to destroy the culture of rapid response. You cannot solve in the response systems the problems that should have been solved in Human Resources.

A mediocre organization can be profitable but never great.

Tools, Technologies and Standards: Overview

This article provides an overview of technologies and standards that will be used as part of this tutorial. Where available links are provided to get more in depth information or for obtaining working copies of these. It is beyond the scope of this tutorial to illustrate all of the features of these and in some cases more information is provided in the articles that follow pertaining to the subject matter of the specific article content.

S1000D XML

To quote from the S1000D specification, version 4.0:

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 has been mandated for the documentation of US DoD systems for all of the US defense services. Each service is at a different stage of adoption and developing supporting specifications and style guides to ensure the applications meet the requirements of the various service systems and missions. In this tutorial a published style guide specifcation from the US Army is used for tutorial examples.

It is worth noting that with the applications of the US Army IADS browser and the implementation of S1000D by programs that are the traditional early-adopters of technical systems prior to adoption by other projects, the use of S1000D for US Army systems is firmly established.

Detailed information for S1000D and terms and conditions for its application is found at the S1000D Organization web site.

MIL-STD-3031A

The governing atyle specification is MIL-STD-3031A Department of Defense Standard Practice Army Business Rules for S1000D: International Specification for Technical Publications Utilizing A Common Source Data Base.

To quote from the standard:

This standard establishes the business rules to be used with S1000D Issues 4.0 and 4.0.1 for the preparation of technical publications required to support the various types of equipment and weapon systems within the Department of the Army and Headquarters Marine Corps. The requirements contained in this standard cover operation and maintenance at all levels through overhaul (depot), including Depot Maintenance Work Requirements (DMWR) and National Maintenance Work Requirements (NMWRs). This standard does not contain requirements for training material.

Note that as of this writing the US Army business rules for S1000D mandate the use of S1000D Version 4.0/4.0.1 and not the latest 4.1 version. MIL-STD-3031A business rules are mandated to ensure the application of S1000D meets the US Army requirements. A working group determines the content of this standard but as in all procurements, contracting officers can waive requirements. In web parlance, Your Mileage May Vary (YMMV).

Copies of the MIL-STD-3031A standard are available here.

Interactive Authoring and Development System (IADS)

IADS is a US Army owned and developed Interactive Electronic Technical Manual (IETM) authoring and viewing system. The latest IADS information including downloadable software is available at this USAMICOM web site.

IADS is an IETM/IETP platform. It is a topic based navigation and display browser for maintenance information that can be combined with the Functional Group Code (FGC) structures to develop and field a consistent and logical means to edit and configure parts, procedures and resources for logistics products. It is not a web browser. It is a dedicated hypermedia system developed for the sole purpose of making it easy and efficient to build interactive electronic technical manuals. This implies that the security issues typically and far too often experienced when using web technologies are not issues for IADS.

History

IADS is a green version of the original Unisys IDE/AS product created by the Unisys design team in the early 1990s. The project team was headed by Unisys project manager, William Schultz. The lead designers and developers were Craig Lykins and Gregg Geiss. The IADS version of this project was procured by William Creel, Richard Grambly and William Campbell for the US Army IMMC. The Unisys product is no longer available and subsequent development of the IADS product has progressed into version 4.0.

The current version of IADS has been completely redesigned to support S1000D and other standards. Errors of design made by subsequent teams such as the use of XML programming instructions that caused IADS to be a cul-de-sac for both information and the teams that used it to develop technical information have been corrected. While this new version is not without obstacles such as slow load time, the continued focus on the IETM application, the modernization of the style sheet system and the free downloads are very good. Kyle Turner and the IADS team are to be commended. Note that alone among the hypertext browsers of the pre-web browser days, IADS is still standing. My compliments to the IADS Team.

Full Disclosure: The author of this tutorial was an early member of the IADS team and is not simply fond of like an old friend but in a somewhat unique position to evaluate its progress and development. There is a lot to be said for dedicated off-the-web hypertext systems.

XSL(T)

The eXtensible Stylesheet Language (XSL) is an XML appiication that can transform XML sources into HTML and/or other XML languages. Learning to apply XSL is a key to rapid response at high quality and repeatable performance. This cannot be overstressed: an XML practicioner who doesn't learn and apply XSL is by no serious definition an XML professional. This language has numerous web sites that support it with examples and online help.

There are multiple versions of XSL and support for them varies. Basic XSL proficicency can speed up XML processing and in large tasks can provide considerable profit advantages and improve the quality and consistency of the XML products.

This tutorial will make extensive use of XSL transforms. These are examples that show both simple and complex ways to apply XSL to S1000D production but by no means comprehensive. The reader is advised to locate and study the numerous examples of XSL freely available.

Lenz Consulting provides a very good overview of XSLT here.

oXygen XML Author/Editor/Developer

A remark from XML expert, Sam Hunting, says it: the tools for XML have improved a lot. In the early days we did use applications such as Notepad because they were affordable and ran well on our not-very powerful desktops. Today neither of these reasons are valid. The new generation of XML tools are affordable, fast and for a well-trained XML author, incredibly powerful. Of this generation, none is better than Syncro Soft's Oxygen authoring and development tools.

• Author and developer support for all of the XML application languages including XML Schema, Schematron, XQuery, XSLT, XProc and more.
• Designed by people who have done these jobs thus all the information the user needs is usually one click away and visible. For example, the XSLT drop down that actively tracks where in the XML tree the user is at coupled to active searching of both the local document and the Common Source Data Base is a very effective way to update information by type and cursor position.
• Very powerful interfaces to non-XML data resources. As this tutorial progresses, it will demonstrate why this is important particularly for S1000D authors.
• Enterprise-capable. The key to speed is to reduce keystrokes and this requires the ability to work with the XML tree in different ways that are provably reliable and resuable by team members who did not implement them. For example, transformation scenarios enable the development of modular transformations that can be put together just in time as needs change. This is critical for rapid response organizations.
• A solid Application Programming Interface (API) for integrating the editor with other enterprise components such as file managers like Microsoft SharePoint. Given that such external systems are widely deployed and well-understood in today's distributed organizations, this is a must have.

Those of us who have worked with print-oriented markup editors know the frustration of trying to do code-oriented operations with them. Complex content tagging for technical manuals has always been one of the hardest applications of XML. It requires schema driven context editing of elements and attributes and the ability to switch contexts seamlessly. Oxygen is the editor for the XML power user. It is a freakin' chainsaw in the XML forest.

You can download an evaluation copy of oXygen XML Editor here.

XML Creator and Utilities for S1000D

XML Creator and Utilities is a standalone desktop XML editor with support for:

• Creating and testing XML applications and style sheets
• Creating and viewing S1000D Data Modules
• S1000D Common Source Data Base file system and search utilities
• Automatic creation of S1000D Illustrated Parts Data Modules from SQL querying of an LSAR-sourced parts database using the Functional Group Code
• Inspection of IETM graphics for inclusion in data modules

This system was designed and developed by the author of this tutorial as a Microsoft Windows Forms Automation (WFA) application using the MS system.xml framework. It is used in this tutorial to illustrate graphical user interface concepts when an integrated editing system is applied to S1000D. It is not a commercially available product.

Notepad ++

Notepad ++ is a freeware programmer file editor. It supports syntax higlighting of various progamming languages and XML as well as tabbed browsing and a rudimentary keystroke macro recorder. It is very popular among open source developers for its size, speed and cost (as in really free).

Notepad++ is excellent for editing and inspecting XML files although it has no XML DTD or schema support and requires that the user be able to correctly construct the XML tree. The syntax highlighting enables the user to find and correct most syntax errors and for the advanced user this can be sufficient to do many XML editing tasks. It is used in this tutorial to contrast editing techniques where multiple fragments are being stored and handled.

For What It's Worth

From time to time you may encounter a self-proclaimed XML expert who will tell you that XML is "just ASCII" and file editors such as MS Notepad are all you really need to do XML work. In the same way that ten thousand monkeys with rocks can shape bigger rocks into 200 ton stones and lift them into place to create perfectly fit walls on the sides of mountains, this is so. If you have the money, honey, they have the time and will manage the monkeys for you until you run out of money. Let the buyer beware.

Introduction

This web site provides information for working with S1000D XML using widely applied techniques and tools for automating production processes. Examples include XSLT transformations and other forms of code that can be applied to increase the capacity of the production organization. These are provided as-is without warranty and the user is responsible for ensuring that they work within the context of the production processes of their organization.

What Is XML?

If I had a dollar for every time I've given this speech, I might take up computer science  )  What follows is the short story.

Take a look at HTML. It is a markup application language. SGML is the parent language (Standard Generalized Markup Language). XML is a cut-down version of SGML for reasons a bit technical to describe here. XML is a meta-language. It defines the characters to be used in the language, how they are arranged and how a program called an XML parser behaves when passing those characters to an application, for example, a formatting engine that does the actual layout of the page. This is important: XML does NOTHING. It is a set of rules. The application of XML is to declare the application language such as HTML 4.0.

Right click on this web page. You should see a menu item (View Source). If you click on that you should see the markup under the web page. It will look like computer code and some of it in the script tags is. Those tags are data for the page controls such as menus. Originally HTML was much simpler but that was thirty years ago when the web was young.

Who decides? Sometimes an application development shop, sometimes a standards organization. Usually an organization such as ATA or ISO or the W3C. In the case of the application language in most use locally, that is S1000D. It is a set of tags used to markup a technical manual. It is defined as a set of data modules, for example, description modules, procedure modules, parts modules, etc. The S1000D tags surround the text to be displayed and there are tags that include by reference the locations of external items such as graphics. At this point, all you have is a heap of tagged text and links.

To render this to a readable page, a formatting language such as XSL is applied to add the formatting information. This is called a style sheet language. It may or may not also be an XML language. Again, as in S1000D the formatting information is just data.

The magic happens when a rendering system takes both of these and combines them into a rendered image. This application is often a browser such as the one you are using right now to see this page. It may be a print application, an interactive web page or both.

The point is an XML application language such as S1000D is a way to structure the data for processing by a computer program.   That's it.   Good practice separates the content, for example the steps in a repair procedure from the formatting information that renders it as say a nested list of steps in a font such as Arial or Times Roman.

Why not put the formatting information in the same structures as the procedural steps as is done in other languages such RTF?

The reasons to do this are the same information can be created and given to different devices using different style sheets. Thus the same web page or technical manual pages can be rendered to your web browser on a wide screen and to a hand held device such as you smart phone and only the style sheet has to change. Another reason is the long term preservation of information is better and cheaper. For example, US Army missile systems such as Patriot can be around many decades longer than the systems originally used to print the manuals and in fact have been. Updates are also easier because information can be added, changes can be tracked and so on without worrying about the final rendering.

It is important to understand these concepts when creating S1000D deliverables.   While it is technically possible to use a document program such as Microsoft Word to create S1000D modules, it is a bad idea and a bad practice.   It stores technical information in a file format that is proprietary and worse, difficult to transform into a different document system.  Thus reuse of the information for different mission objectives becomes more expensive.  It requires the customer to keep that proprietary system up to date with that by which the information was created and this creates an unhealthy contract relationship between contractors and the customers.  It is called entrapment.

Entrapping a customer in a contract is an old, maligned but often pursued goal in business.  Caveat emptor.

Purpose

This information is being provided in response to observations over a number of US DoD contractor sites where the techniques applied to XML production for S1000D projects are ineffective for enabling cost-effective rapid response to mission objectives for that information.

Too many organization rely on obsolete processes inherited from years of creating and managing technical information with older SGML-based products. Further in too many cases the management and planners for the projects have fallen behind and failed to master even the earliest production potentials of XML. Basic technologies such as XSLT are neglected and instead these organizations rely on tagging armies and excessive man months to do work that basic automation can do much more effectively and cheaply.

Overview

Several technologies and standards will be used as part of this tutorial including:

• S1000D XML
• MIL-STD-3031A
• XSLT
• IADS
• Oxygen Author/Editor
• XML Creator and Utilities for S1000D
• Notepad ++
• Microsoft Excel
• Microsoft Visual Basic
• Microsoft Access
• Microsoft SharePoint

The examples given here are intended to be self-contained and explanatory. Readers who wish to work or apply the examples directly will in most cases require some or all of these technical implementation. However it is not the intent of the author to market these and no fiduciary relationship to the makers of these packages exists. All of these in some form are standard office desktop products.
While S1000D production systems dedicated to creating S1000D products are available on the market, this presentation is not intended to explain them. Many are expensive enterprise systems and for large organizations managing multiple projects, these are well-worth the expense. This weblog is provided to teach nuts and bolts techniques that do not require these enterprise systems.
Also, some examples given can be improved with newer applications of the enabling standards such as XSLT. In such cases if the reader has alternatives that provably improve the examples, they are invited to cite where these can be obtained with alternative example code that can be included in this web site. Code fixes for errors in the examples are also welcome as long as they are open source and unencumbered by intellectual property claims.
In the following article the role of each of the technologies listed above is explained in the context of this presentation.