Thursday, August 06, 2015

S1000D IPD Generation

As, no doubt, those of you who need to create S1000D IPDs will know, creating and editing this type of Data Module is not easy at all.

Legacy Conversion

A good few years ago I was involved in a project to convert loads of Handbooks into a very early version of S1000D (1.6 actually). There were quite a number of pages of parts list to be converted from hard copy. Some of these parts lists extended to thirty pages or so - so what to do.

As most of you probably know the IPD structure is not the easiest to work with. I remember that most of us were horrified when we saw the DTD and I also remember the various comments which were articulated when we were told that the structure was for the transfer of data between databases - not complimentary is putting it mildly. In those days the majority of Data Module creation was done by Technical Publication contractors who, in the most part, did not have the skills required to handle this type of structure.

At that time the scanning and ocr process was pretty well sorted but the next stage of getting this data into an IPD, without pain, was another story altogether. About the only way then was to get the data into a word file and process the table with a template which contained Visual Basic code. I am happy to report that this was pretty good with the IDStatus area of the Data Module being entered via a series of drop down selection fields. For the time this productivity tool was very effective for what it was designed for.

What about today

Today there are a number of our clients who do not have the luxury of a S2000D compliant database which, of course, is supposed to export IPDs to order taking care of the IDStatus area of the Data Module. A number of these clients mostly have the parts list provided to them by their client in a spreadsheet form which is part way there (at least the data is in electronic form).

So we are left with looking for something that will take the pain out of generating IPD Data modules. And very recently I have been playing with just such an application.

The Painless Way


As most of you know I don't usually push products from Mekon, I believe that this blog should be more about the S1000D Environment and Community covering problems discovered, tips, helpful advice, and, OK, Moans. But in this instance I think we have a great standalone application that can really take the pain away from this job.

The process is easy:-
  • Take a spreadsheet containing the parts list data (with column headings),
  • Above the parts list data in the spreadsheet add important information such as 
    • Data Module code,
    • Issue number,
    • date,
    • Illustration information
  • Map the location of the various items of data to the schema elements and attributes in an IPD Builder which has a very easy mapping function (this can be saved in a 'mapping file')
  • Then press the build button.
  • The result is a perfectly formed IPD Data Module.
  • If you forget something important you will get a pop-up window to enter the data during the build process (you can modify the mapping file to correct this).

If you add the extra information into the same location as the first spreadsheet you can keep on running it to get your IPD data modules. Different spreadsheet layouts can be accommodated by having different mapping files (which you have created). Where there is more than one item in a spreadsheet field some straightforward additional scripting language is provided to accommodate this problem.

Monday, October 20, 2014

S1000D and DITA

Do You Remember?

I don't know if you remember, was it earlier this year or last(?), that there was a flurry of activity around the topic of S1000D and DITA. A group of people had decided that the way to go was to create a DITA which conformed to S1000D.

The presentation was very interesting and, no doubt for some, it was the next exciting thing coming along for the Publications Industry. But for some of us it just didn't have it - and no this is not sour grapes. This topic has come to mind because of training courses that I have run for some clients of ours this year, both face to face and remotely via the internet.

I am not unfamiliar with DITA because:
  • Our company has a core of DITA specialists
  • Adobe FrameMaker can be used to handle DITA projects
  • Adobe FrameMaker comes ready for DITA out of the box.
So given the above why is it that I am not sure that DITA S1000D (or S1000D DITA?) is the way to go.

Why not?

Well, it is my observation that certainly the newbies (sorry but it is not meant to be a derogatory term) to S1000D Authoring have enough to cope with using all the features out of the box. This also applies to those who have been involved in S1000D for some time and who are experienced in that area. Quite often we get questions like:
  • Do we have to use all these different types of Data Modules?
  • Do we have to use this new Technical Information Repository stuff?
  • Do we have to use all these elements?
Of course the answer to all of the above is a resounding NO unless, that is, you are unfortunate to be a Technical Publications Contractor working for one or two of the companies that are insisting on using all the bells and whistles. The majority of users and main contractors/design authorities are not using a number of the extra and most recent features.

So when it comes to DITA and the ability to extend the functionality using specialisms it just leaves them cold. They have no notion or need to learn all sorts of extra stuff. The basic S1000D is quite good enough.

Listening to the guys in the presentation they were clearly very enthusiastic about it. They had be nurturing this arm of S1000D and were very familiar with all the nuances.

It is not just the newbies that don't want to go down that route. My chats with experienced S1000D Authors reflect the same attitude as those not very familiar with S1000D.

In one thread that I read there was the admission that "Both S1000D and DITA can be intellectually challenging to deploy and authoring S1000D data modules by assembling DITA chunks could add an additional layer of unnecessary complexity to your project." I think that this is probably an understatement.

So where are we?

A recent search of published material on the subject produced a very interesting result. There was a lot of information prior to 2010 and not so much post 2010.

Internally within Mekon we came to the conclusion some time ago that if a project was based on part numbers and had a long life then S1000D was the solution and we have seen nothing to change our view on that. If the project is software based (and other sort of related areas of work) then DITA may be the answer.

This was also the view of a presentation given in 2014 (DITA and S1000D Different verses to the same song?) where there was a flowchart included in the presentation. This is the last bit of the flowchart is shown here and I think that it shows that the Mekon view is, on balance, still right.

Overall there is the problem of having something that is well documented to work with. S1000D fills that criteria (well almost - having just spent some time trying to find something specific in the spec and failing) and all who use it know what is required of them. Some of the more recent additions are not really necessary and you can tailor the specification to meet your need - and this is allowed within the rules.

I'm NOT a Luddite

I am not a Luddite - honest!. I will (and am happy to), and have embraced new features, technologies etc. when and where they enhance the working environment of those people who have to document a whole range of projects and deliver the information to the end user in the best way for them. After all the maintenance and technical guys are our customers - the guys who use the information we write to do their work.

As evidence to my remark about not being a Luddite - I was the innovator who designed and delivered a touch screen handbook system for a complete train to a large London Based transport organisation in the early 1990's. Navigation was by means of graphics and this was before the days of Windows - so much easier now. (As an aside I met someone last year who knew what we were doing who commented "They are still not doing what we did then are they?")

So, I do ask the 'Innovators' to have pity on the technical authors who just want to do their job by using easy to use software configured to work with S1000D and not have to invent extra bits when they think that something extra is needed. S1000D works well, it has been around for a number of years now and has become reasonably robust (excluding the odd hiccough of course). Technical Authors (or Communication Operatives as I saw the occupation advertised) in the S1000D arena, even those just embarking on the journey do find most of S1000D Logical and relatively easy to employ in their day to day work.

Of course you may not agree. Bet you that there are a number that don't - always the way!