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
hello
ReplyDelete