I’ve waffled on about single source and our plans for long enough so, as we are finally starting the process itself, I thought I’d capture some information as we go along. However, it’s probably good to set the scene, so I’ll cover that stuff first. Over time you’ll be able to see all the posts related to this work here.
How? – how do we do it?
Once we’d agreed that single source would provide us with a good solution (it’s still not ideal, but nothing ever is..) the next question was “How?”.
Having followed the technologies in this area quite closely over the past few years my immediate thoughts went towards a DITA enabled solution. The basic topic types and methodologies fit well with an Agile environment so there would be fairly immediate benefits once we got the system up and running. We spent some time investigating our content and planning how best to leverage DITA to our advantage and once we were happy that it would meet our needs (with less over head than adopting DocBook) we looked at the technological challenges of adopting a DITA based system.
And that’s where we hit the biggest block. DITA is an excellent methodology but still lacks simple/cheap tooling support (it would take upwards of several thousand to fully implement a DITA solution, whereas a bespoke solution could cost considerably less). Other considerations (we have JavaHelp as our online help format) also came into play and, after some investigation of other XML based tools we decided to go with Author-it and base our working practices around the DITA methodology and topic types.
We did consider upgrading our legacy applications (FrameMaker and Webworks) and configuring them to give us a solution that would meet our needs but even the rough estimates for that work took us beyond the cost of our chosen solution.
One caveat to this is to note that I have used Author-it previously and, whilst it is not without its foibles (which application isn’t) it hits the sweet spot of functionality versus cost. None of the rest of the team have used it but that would be the same for any other new tool and was considered as an upside to keeping the FrameMaker + Webworks solution.
A second caveat is that I’m fully aware that, in due time the tool vendors will get on top of this problem (MadCap already seem to be ahead of the others in this area), but alas the timescales don’t suit us. Worst case scenario is that we ditch Author-it in a few years, export the content to DITA XML and import to a compatible tool that meets whatever needs we have at that time.
What you’ve outlined is one of the biggest hurdles for all organisations that want to move from an unstructured methodology to a structured one – how long (and how much) to get there. Once the enthusiasm of a DITA or custom schema approach dies down and people realise how much effort will be involved in migrating or re-writing existing content to meet the structure, at the same time as meeting their day to day work requirements, the task has become huge and the true cost almost unknown.
When you say several thousand to implement a DITA solution I think you are underestimating the cost dramatically – every hour that a team don’t spend writing (meetings, problem solving, struggling with a new tool etc), every hour a developer spends updating a schema/specialisation/XSLT, every day a project slips, all add to the true cost of the project. When management add this up the cost of tools is often minor in comparison.
According to our clients this has been the biggest gap – managing and evolving non-compliant Topics when the technology requires compliance to deliver an output – eg. the XSLT or DITA Toolkit chokes because your content isn’t yet fully compliant. We talk to a lot of organisations migrating from Frame/RoboHelp/Flare (and even Word) and regardless of technology the big hurdle is the need to continue meeting deadlines while migrating from unstructured content to structured content.
So in the 5.2 release of Author-it we’ve added template-based structured authoring where, once content is imported (or written), you can apply a DITA or other structure over the Topic and see exactly where you do and do not structurally comply. Once your Framemaker or RoboHelp document is imported you immediately see which Topics are compliant and which are not, *but you can still publish your document*. You can continue to meet deadlines and always have complete visibility of which Topics in which projects need to be updated to meet your structure standards.
The Author-it Structures are Object templates that can be applied en masse, and if you change the template all Objects inherit the new structure rules (or show you they now fail to comply). Workflow controls mean Topics *must* comply at certain Release States (‘Draft’ can be non-compliant but ‘Released’ must be compliant), and Publishing Profiles remove all non-compliant topics during publishing if you use the DITA Toolkit or similar XSLT processor.
Finally, you are correct that tool manufacturers are working to get on top of this. The successful ones will be those that solve real business problems with technology, and don’t just tick technology boxes.
Hi Matt,
Interesting news about 5.2, that’ll be interesting as we are already starting to structure imported topics using DITA as a ‘template’, actually being able to use DITA for that will be a boon.
The main reason we want to do things this way is purely to protect our content for the future. A ‘get out’ strategy (hey, who knows what will happen in the next 3-4 years..