If DITA seems like a good idea, but you cannot make the case for it, you can move towards structured writing and make your documentation “future-proof” by meeting the standard half-way.
At the company I work for, we tech writers created manuals in parallel, but separate to online help. Over time, this gave us a documentation set that was inconsistent in places and hard to maintain to boot. Topic-based authoring which reuses topics in print and online can fix that, of course.
First, a documentation standard
Deciding on the method is one thing, but we also wanted a consistent structure that made the documentation easier and clearer to use – and easier to maintain for us writers. That required a model that specifies which kinds of topics we want to offer, how these topics are structured inside and how they relate to one another.
As we looked towards a documentation standard, we had two options:
- We could create a content inventory of our documentation, analyse and segment it to tease some structure from that.
- Or we could rely that others had solved a similar problem before and see if we can’t use the wheel someone else had already invented.
Turns out the second option was quite feasible: The DITA 1.2 specification gives us about all the structure we need – and more. We left out the parts we didn’t need (for example, some of the more intricate metadata for printed books) and adopted a kind of DITA 1.2 “light” as our information model.
Second, the tools
Note that I haven’t mentioned any systems or tools so far! Even though it happened in parallel to the rolling out topic-based authoring as our method and DITA light as our information model, the tool selection was mainly driven by our requirements on documentation workflows, structure, deliverables, and budget.
The tool that suited us best turned out to be MadCap Flare – even though it doesn’t create or validate DITA!
Using our information model in Flare, we believe we get most of the benefits of DITA – and considerable improvement over our less-than-structured legacy content. And speaking to people at WritersUA 2011, it seems that we’re not the only one to move from less-than-structured writing to XML and something “close to DITA”.
Technically, we’ve defined the DITA elements we need as divs in the Flare stylesheets, but otherwise use the straight Flare authoring-to-publishing workflow. Flare is agnostic to whether a topic complies with DITA, is somehow structured but not complying or totally unstructured.
The benefits of DITA, half-way
To us tech writers, the largest benefit of DITA, half-way, is that we can actually do it. We could not have gotten away with DITA, the full monty, which would have required a much longer project, a much bigger migration effort and hence, uncertain ROI.
For new topics, we are committed to writing them structured, so they follow the information model. To migrate legacy topics, we’ll have to ensure they have an identifiable topic type and a suitable heading, but we can cleaning up their insides in a “soft fade”, moving them towards structure one by one. This gives us a quicker win than cleaning up literally thousands of topics before having anything to show in the new method, model or system.
So we will have been working in Flare and with our home-grown information model for a long while, before all topics actually comply with the model. But then we will have a documentation set which we can feasibly move into real structure, whether we opt for DITA or some other XML-based CMS, with or without a CMS.
This post is an elaboration of a comment thread on the “Why DITA?” guest post on Keith Soltys’ Core Dump 2.0 blog.
Filed under: change management, content management, DITA, MadCap Flare, managing, single sourcing, structured writing, topic-based authoring |
Kai's Tech Writing Blog 
You just knew I’d reply to this, didn’t you? I have no issue with this approach. I think that it’s a very good first step to a move to DITA, and I know from repeated experience, making the ROI projects for DITA isn’t easy in every organisation. DITA has to fit and it seems you did your homework, so all the boxes are ticked.
The only thing I wanted to point out is that the last sentence: “But then we will have a documentation set which we can feasibly move into real structure, whether we opt for DITA or some other XML-based CMS.”
Seems to imply that DITA is one type of XML-based CMS, and you may opt for it or an alternative. For the benefit of readers who might find this confusing, I just wanted to clarify that DITA is not a CMS of any kind.
DITA can be (optionally, but often it’s recommended) stored in a CMS and is a form of XML. So, you cold go with DITA, some other XML-based content standard, and you could do both with or without a CMS for a total of 4 potential options:
DITA + CMS
DITA no CMS
Other XML + CMS
Other XML no CMS
Hi, Noz, thanks for your comment. Yes, well-spotted! I wish I could claim it was a sort of easter egg to see if anyone actually reads all the way to the end – but it was only poor editing.
Given how much confusion we see over DITA, what it is and is not, it’s important to get this right. So thanks for pointing it out. I’ve now crossed out the offending phrase and corrected it.
[…] upon Kai’s Tech Writing Blog, this morning, because of the eye-catching headline, “Half-way DITA: Why some is better than none.” Turns out the second option was quite feasible: The DITA 1.2 specification gives us about […]
Hey Noz! Yeah, I saw that as well, glad you addressed it. I like this approach, and find it quite novel. It’s a great move toward a full implementation, but it’s also quite fine all on its own, if that’s all that is necessary. Gave you a mention on our blog, Kai, this is the first I’ve seen of Kai’s Tech Writing Blog, and won’t be the last!
-Vincent
Hi, Vincent, welcome and thank you for your kind mention.Good to hear that our somewhat unorthodox approach makes sense – it’s a daunting journey to be sure, even more so because there are few (metaphorical) books to go by… 🙂
Interesting post, thanks, and also nice to hear as we came to very much the same solution. We chose Author-it because we wanted a CMS to manage and publish the content, and make reuse easy, and also because it supports structured writing, albeit based on styles rather than tags. So we use the DITA information model that way.
Working well so far.
Thanks, Daniel, we apparently went the other way, not least because we liked Flare’s open file approach. We get a lot of mileage out of that and throw loads of scripted topic files at Flare. We’ll use TFS for the versioning. Good to hear that others find similar ways of using DITA!
Interesting! We are in the process of implementing the very same thing – Flare with a half-way DITA. If you don’t mind, it would be great if you could contact me privately, as I’d love to ask some questions about how you implemented this in Flare (setting up the CSS, etc.). I’m in Germany, too, by the way.
Cool! And good to know we’re not the only ones trying something like this… 🙂
I’ll mail you, but to answer your question regarding the Flare CSS. We created div classes for the DITA elements we need. We came up with tag names that group and sort our element tags, so we writers can easily see the correct order from the “Create Group” selection box in Flare.
For example, for concept topic elements, we created:
div.c1_Introduction
div.c2_Definition
div.c3_User_Scenario
For elements that can appear in several places and topic types, we have:
div.a_Example
div.a_Note_Warning_Tip
div.a_Section
[…] The information model defines the 4 topic types we have and what each type contains internally. It’s basically “DITA, without the boring parts” about which I blogged previously. […]
Since it’s not DITA, and in fact it’s a very long way from DITA, shouldn’t we find another name for it? UnDITA? DemiDITA? SimplifiedDITA? MadDITA? HalfDITA?
No, any name that includes “DITA” would be suggesting a watering down of the standard, not an improvement. Seems like a better idea to find a new name based on XML.
By discussing the “halfway” concept, we’re just suggesting a better way of thinking about structure. And this new structuring concept is really inspired by XML, not DITA – just as DITA was.
A new standard could be based on how XML inspires us to think about finding new patterns that just improve documentation flow, without having to lock each tag down for re-use and ease of localization. The main objective of improving the company’s ROI should take a back seat to good content, since that is what will really sell and support new products..
The financial challenge of serving so many more users in different countries is of course significant, but in my view, DITA evangelism has gone way too far, making writers value clever taxonomy above conveying the technical information users need clearly and competently. With DITA, so much energy has to be put into nailing down each leaf of each tree that the forest sometimes burns down.
So should we be saving money producing localized documents at the expense of producing poor content? I regret to say that I have seen that happen.
That should be the new “halfway” concept we’re talking about. Any suggestions for a new name?
Thanks, Bee, for your thoughtful comment!
In hindsight of more than 2 years, I’ll admit that the “halfway DITA” moniker owed a lot to the situation at the time. I wanted something that implied structure, an adherence to an accepted industry standard without being overly rigid. So I needed a term that sounded like, well, a palatable compromise – a watered down standard, if you will. So I’m guilty as charged! 🙂
Now, two years later, I can see that our information model is still inspired by DITA, but our actual implementation is not DITA-compliant. And that’s okay, because it serves us well and is still future-proof as far as we can see.
I’ve also followed case studies of DITA adoption carefully, and we fall into that vast middle ground where DITA can be attractive and beneficial, but we cannot make a compelling business case for it in our current setup.
Which is basically a long way of saying: I agree with you, Bee. We’ve come to a very similar conclusion since I first posted this.
I’m a bit hesitant to sign a call for yet another standard. I’m actually quite happy with a custom X(HT)ML-based information model which is codified, so we can train new writers and, if we absolutely want to, we can even validate content. Whether this is an agreed-upon standard seems less important.
I’m always game for coming up with good names, but my first ideas, the obvious “DocML” or “DocXML”, are already taken…