“DITA Implementation in a Geographically Dispersed Team” Presentation

After JoAnn Hackos’ brief introduction, this was the first talk I attended at the DITA Europe 2010 Conference in Vienna. As I am also dealing with issues surrounding working with DITA in what could also be called a “geographically dispersed” team, this seemed like it was right up my alley.

The presentation was given by Gjertrud Kamstrup and Tony Self. Gjertrud works for Visma Software International AS, which is a payroll processing firm located in Norway. It has 4,100 employees, is responsible for more than 220,000 customers, and more than one million individuals use their services every day. Tony Self is consultant with a firm called Hyperwrite which is located in Australia. As he pointed out, if you drill a hole down through the Earth through it’s center and continue on through, you end up pretty close to Visma’s HQ in Oslo. Though I was expecting to hear a presentation on how writers who were distant from each other managed to work together, the geographic distance between consultant and client seemed to be what they were hinting at in the title.

The firm’s story in its move to DITA was this: they were using MS Word and HTML to produce their docs, and they were looking for a common way to do their documentation. They also wanted their docs to be authored exclusively in English, which would then be localized. The desire to embrace open source software was another deciding factor for them in their new doc efforts. They also needed to publish in PDF, HTML, Eclipse help, as well as context-sensitive help.

The authors were 20 QA staff who needed to be trained to use DITA. From the description it sounds like they were a very “green” team, with nobody on the team having any experience as a technical writer, never mind structured writing.

For the training, they managed to instruct the users on the basics of technical writing in general and then on DITA, done as a crash course over two sets of four-day sessions. The tyranny of distance made itself known when it was found that the new DITA authors needed further help — apparently because there was a time gap between when the training was given and when the new authors were expected to write in DITA — compounding the problem. In order to overcome this, they ended up using Skype and GoToMeeting extensively, along with TWiki as a central repository on how the writers should author in DITA XML.

When it came to choosing authoring tools they looked at their processes first, and then chose a tool to support that process (a very sensible approach). They ended up choosing oXygen for authoring, which was a good fit for the people on the team, who are more technically oriented and preferred this over software. For publishing hey chose WinANT Echidna and the DITA Open Toolkit. For their “CMS” they used Subversion, which is not really a Component Content Management system, but a version control system. The reason for them making this choice was that they needed to get up and running quickly, and they plan to chose a proper repository later. Most interesting to me was their use of Madcap Flare to help migrate legacy content — this not a typical use for this software, which is a help authoring system. One of the member of their developed a conversion tool — named “Sissel’s Generation Tool” after it’s author — which auto-generated 13,000 topics from their existing content, saving them about a year’s worth of work.

As they continued to use Subversion as their pseudo-CMS, performance became an issue as the topic load grew. To get around this they first used a program called Synchro, then Tortoise to synch their files. TWiki was used for project coordination, and also used for setting standards and guidelines.

Among the things they believe they did right was to build a prototype and test it thoroughly, and to develop writer templates within oXygen where the writers simply had to add their content.

One of their key regrets was having spent a lot of time on legacy migration, more than they think in retrospect was necessary. For example, they often found that rewriting tasks ended up being faster than trying to convert them from legacy. Also, some things just did not convert well which also added time and expense.

They are now working on improvements to deal with ongoing variations in quality, which they consider their major challenge going forward. This includes dealing with different variations of the English writing, plus coding in DITA — this is where devising style guides for both English usage as well as devising a “house style” for coding in DITA would likely help. Their scope included jumping into using DITA in production fully with 15 different product lines, and they now have tens of thousands of topics in Subversion. So seemingly a good case study of a production environment in DITA still in it’s early stages.

One question from the floor (which I would have echoed) was: when do they plan on getting a CMS? Their response was that they did not see the need for a full CMS as being critical. This struck me (and likely others in he audience too) as being short-sighted, especially given the issues they are already facing using Subversion, which was not designed for how the purpose they are putting it through, and which I suspect will become more of a bottleneck for them over time. (To be fair other factors — like budget — may have come into play here).

I hope they return to present at future conferences, as it will be interesting to see how their processes and systems evolve.

In the end I was disappointed that the subject of the presentation did not meet my expectations as to what I thought they were going to be talking about — very little of the talk focused on the geographic dispersion of he writers, more so for the consultant hired from the other side of the planet. Still, it’s always interesting to see how other people do DITA.