Tuesday, October 11, 2016

Working with Warnings and Cautions

Way back When

We have just been involved in the handling of Warnings and Cautions and what was being asked for set the OGCs (Old Grey Cells) grinding away trawling up the early days of S1000D. To be precise Issue 1.6 (Change 6 as it was known then). I remember that the UK MoD spent quite a time looking at just what should happen when a Warning was being used.

Lets put on one side the IETM action on being shown a Warning. Although the method determined on was a bit of a contentious issue with the end users it was the only way to make sure that it was put in front of them. Whether they read them is, of course, another matter.

The mechanics were that one referenced a Warning in a Data Module and each warning should be located in a separate Data Module. Indeed the DefStan group created quite a number of special Hazard Warnings and Cautions which were related to specific situations. The mechanism was straightforward. Reference a warning/caution and it was brought up in front of the user. Each Warning or Caution was in its own Data Module. Easy! Easy to find and easy to modify.


OK, so I know that you don't have to use everything that is provided within S1000D, but who thought up the 'latest mechanism' I wonder. You know, the one which stuffs all the warnings in one or more repository files which then has to be referenced (file and warning id) which is then inserted on the fly.
We have two problems here as far as I can see.
  1. You have a file which contains theoretically hundreds of warnings. So when it needs updating first work out which file contains the one that you need to change and then find it in the file itself.
  2. Just how easy it is to share the warnings between projects?
By having a single warning in a data module the question of updating is much easier, and the ability to share with other projects is also easier.

The question of sharing Data Modules form me was addressed very early. When I was working for another company we had the MoD project manager for a large item of equipment visit us. He has been told that all the legacy Data Modules for some of the equipment which was common across many platforms had to be converted to the latest issue at that time. The reason was that the different issues were incompatible. We were able to demonstrate within 10 minutes that we could create an IETM using Data Modules from the three issues available at that time and they worked perfectly well. So if this is being held up as the reason for the new system it doesn't wash.


A lot of the problems which occur due to changes which have not, from the end users point of view, been thought out. In a modified system this problem could very easily be solved by making available to a wider audience the proposed changes before they became 'caste in stone'. It is very easy to place a time limit on the 'consultation' period. I realise that this time would perhaps delay the publication of new issues but overall that would be time well spend.

I know that I did mention this mechanism and pointed to the W3C way of working as a possible solution a long time ago. It is certainly a lot easier and quicker than a British or any other standard institution mechanism.

The last time there was deathly silence so I suppose that the same will happen again.

Thursday, September 01, 2016

The Spread of S1000D

Several Years Ago

Several years ago, to be honest more years ago than I care to think about, my job was as a Radio Officer in the Merchant Navy. My observation then was that it was a good job that my training had been very much hands on with the current equipment of the day because the handbooks provided for pretty well everything that came within my sphere of interest (pretty well everything electronic) were awful. After a couple of years I went on a course for a new and improved radar and those handbooks were even more dire than the ones in use at the time.

As far as I could see the Engineers were in the same boat, so to speak. They were all time served apprentices in Marine Engineering who had converted to Seagoing Marine Engineers gaining their 'Tickets' at sea. They did not need handbooks to tell them about their 30 ft High 6 cylinder, vertically opposed, turbocharged, Doxford Marine Diesel. They had been in the Doxford yard and built them. Their documentation was limited to copies of the manufacturing drawings.

And when I came ashore and moved into technical documentation I sort of  thought that there had to be a better class of Handbook. Ones that were not riddled with errors, with the information presented in a way that it was very easy to find the bit that was the focus at that time. In other words documentation that was not so dense that it did not take ages to find out what you wanted to know

A bit later

A bit later I got involved in proposing a handbook system for a large Multi-site mining machine manufacturing company. They had several types of mining machinery which could be manufactured in any one of five or six sites around the world. Each machine was made up of several modules with a high degree of commonality and each site was responsible for one or more of these modules. So what to do about handbooks.

The company had a very fast inter-site network so the concept of using S1000D with the CSDB at one location was almost a no-brainer. The handbooks could be put together as required using the Publication Module which could then be 'Published' as and when required by any of the sites.

Well?  No, they did not go down that route choosing instead to use Dita. By the time they realised that it might not have been a good choice for their particular project it was too late and they were committed.

I have always been a keen advocate of S1000D for a lot of projects, particularly now that the software required has become well established, and in most cases reasonably priced. I guess that one of the reasons why take up has not been so rapid is because when a novice picks up the Specification they loose the will to live. They do not realise that they don't need all of it to have a really good system up and running fairly quickly.


Very recently I have been involved in the latest issue of the Shipdex specification. A full circle so to speak. A specification which is for use in the marine environment which is now at Issue 3. Very much a set of Business Rules which sit on top of S1000D the requirements are straighforward and relatively easy to understand. There are some formatting changes (to be expected of course) and some specific use of attributes (which don't get in the way of S1000D).

It is very refreshing to see the emergence of this specification. I don't know how common its use is but even if it is just starting its use should be encouraged.

Any others?

Of course this begs the question. Are there any other non-military/aerospace projects which are using S1000D?