Half-way DITA: Why some is better than none

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.


Short-sighted seduction: Tech comm as a task

Treating tech comm as a task, not a profession, is seductive, but harmful.

This is the story of how a seemingly sensible management decision about documentation has inflicted avoidable damage on a product. Read how the idea that “anybody can write” can backfire.

Best intentions

Imagine a software company. They decide to revamp one of their products. It’s gotten a little long in the tooth and deserves a renovation. Requirements and designs are written, modules are developed and tested. Documentation was previously understaffed, but that wasn’t a severe problem.

The shipment date approaches, and things get a little tight: Usability and performance tests lead to additional developments which lead to more tests. The flexible corporate culture pays off as they assign developers and testers from other units to revamping tasks. Meanwhile, documentation takes a backseat: Compared to development and test, it is less important for shipment, hence it is less urgent and gets less attention.

Original sin

Then the lone writer speaks up: He cannot keep up with more developers who keep changing the product at a more rapid pace. His manager has to watch the budget and cannot take on more people. So he does the most sensible thing. He breaks documentation into several tasks and assigns them to whoever has time and knowledge. After all, how hard can it be…?

So developers write online help. They build the windows and can explain how they work. Testers write the release notes. They test the changes and new features and can describe them. The lone writer writes the user manual and coordinates the other writing tasks.

And they launch on time, barely so, with a few glitches, but – phew.

Merrily chugging along

Fast forward, one year later. They develop version 2 of the revamped product. The lone writer has left. A tester will coordinate the documentation efforts. After all, how hard can it be…?

The online help and the release notes come off as before. No one has time to update the user manual, so they postpone it. From the manager’s perspective, documentation as a task works and makes it easier to distribute all tasks among all developers and testers.

Too late

One more year later, there are problems: After shipping version 2, customers started complaining that the documentation was incoherent. Some online help is more helpful than other entries. The release notes describe features that are neither in the online help nor in the manual. The documentation in general is now seen as a burden and a competitive disadvantage.

A business consultant takes a close look at the documentation and finds the complaints are justified. Much documentation focuses on features and reference information. Customers ask for workflows how to set up and operate the product, which is described in the outdated manual.

Lesson learned

As far as technical communication is concerned, I think there is a single simple lesson here: High-quality documentation requires a professional who is responsible and accountable, just as in development or test.

There are two reasons which I think managers should understand:

  • To write effective documentation which can be maintained efficiently and used effectively requires experience and standards. To assign documentation as individual tasks creates incoherent, unmaintainable documentation with overlaps and gaps.
  • As in development and test, what is seductive and cheaper in the short run, costs more money in the long run.

5 steps from legacy documentation to topics

To move to topic-based authoring, you need to convert existing documentation into topics. The efforts shouldn’t be underestimated, but it’s actually a pretty straightforward process. I’m describing how to convert sections in manuals, but it’s much the same for most content, whether it’s FAQs, wiki articles, training materials, etc.


  • Some knowledge of topic-based authoring. You should know the topic types you will use, for example, concepts, tasks and reference topics.
  • Have a tactical framework. Ensure you know the documentation structure you aim for and how you will get there in a project. Consider for example the Top 4 tactics to structure legacy documentation.
  • A style guide to which your documentation complies definitely helps.

1. Identify topic type(s) per section

Define each section in your manual as one of your topic types, for example, concept, task or reference.

If topic types are mixed…

A common problem at this point is that you may have topics that mix topic types. For example, your topic contains concept information and task information. Or task information and reference information. For details, see When topics don’t quite work.

2. Re-chunk sections to make them topics

Redistribute your content so each section becomes a topic:

  1. Cut out everything in a section that doesn’t fit the selected topic type and put it aside.
  2. Ensure that the topic that remains:
    • Is either a concept or a task or a reference.
    • Presents only one idea.
    • Has only one purpose.
    • Can stand alone, in context with others.
  3. Take the content you have cut out and put aside and do one of the following:
    • Integrate it into an existing topic where it fits better.
    • Create a new topic for it.
    • If it’s not relevant, throw it away. 🙂

If topics are too complex…

A common problem at this point is that you can end up with one or several topics that are too complex. Then you can try the following:

  • If you can describe a topic’s content as two separate, but related ideas, turn it into two sibling topics.
  • If you can fully summarise a topic’s content only as a very complex idea, turn it into a parent topic and create children topics for it.
  • If it’s a long procedure with more than 10 main steps in a top-level numbered list, try to cut it into two topics approximately in the middle.

3. Re-sequence your topics

Re-arrange the sequence of your topics, so they flow nicely when users read not just one or two of them, but need to learn a complete setup or operational process.

  1. Verify that your topics are in the best possible sequence and re-arrange them if necessary. You might want to try these categories:
    • Setup, in the sequence of tasks.
    • Operations, in the sequence of tasks.
    • Reference topics, in alphabetical order.
    • Concept topics can either appear as a section of their own, ordered from the large/general to the small/particular, or among the other topics as appropriate.
  2. Verify that your topics are complete and add topics, if necessary:
    • Do you have concept topics for all major elements in your task topics which explain what these elements are?
    • Do you have task topics for all concept topics which explain how to set up and operate the elements

If the topic sequence doesn’t flow nicely…

A common problem is that the topics don’t flow as nicely once you have chunked them into stand-alone pieces. In this case, add some “glue” topics which orient readers and ensure a good flow, for example, at the beginning of chapters in books. Consider including these glue topics only in print deliverables; maybe they are not necessary in your online help.

4. Rewrite headings to guide readers

Often your legacy section headings work in the context of your manual, but don’t give users enough orientation when they read just one or two topics. Rephrase them so users can quickly dip in and out of your documentation. Keep these guidelines in mind:

  • Reflect the user’s need or goal in the heading.
  • Phrase headings so users know what’s in the topic when they see only the heading in a link in another topic.
  • Try to make headings unique so there’s no confusion when they appear in search result lists.

5. Add links between related topics

Ensure that your topics have links or cross-references between all related topics:

  • Do your concept topics link to corresponding task topics – and vice versa?
  • Do your task topics include or link to prerequisites and next steps?
  • Do your task topics link to corresponding reference topics?

Your turn

Do you find these steps helpful? Have you converted documentation into topics before? Please leave a comment.

All aboard! Onwards to structured authoring!

Our team of technical writers is embarking on a journey towards structured authoring. With 10 writers, we’ll move from an unstructured Word to PDF/CHM environment to a structured Flare to WebHelp/PDF environment. Or I should say “semi-structured”: We do have an information model based on DITA, but we won’t actually be able to enforce it with Flare (which we knew before we chose the tool).

It’ll be an interesting cruise, to be sure! Four writers already apply topic-based authoring rather than the previous free-form documentation guided mainly by common sense. The others have had training, but no real opportunity to write topics continuously. We have drafted tighter new processes to draft, write, review and edit topics to replace the previous loose processes of writing and reviewing, but they are not in place yet.

And then there’s the new tool, of course. Only one of us has worked with Flare before. Many of us are excited about getting Flare. Some really like it – what we’ve seen in several demos so far. Others just really loathe the current writing environment.

“Regarding the pain of others”

So as we’re about embark, I’ve been looking out for others who’ve taken the trip before. Scriptorium’s State of Structure webcast has been very helpful: Its results of a survey among 200 tech communicators helps to position us in relation to others who are currently implementing structured authoring or considering it. It also collects some mistakes respondents have gone through. I’ll just be quoting a few select points, but the whole webcast by Sarah O’Keefe is totally worth checking out, so thanks to Scriptorium for making this webcast available!


The top reasons why survey respondents (consider to) move to structured authoring made us nod emphatically: Reuse, consistency and cost savings are also at the top of our wish list of achievements. Looking ahead, it’s promising that the majority of respondents achieve these goals.

We’ll also take other goals that respondents achieved, whether it’s to automate processes or to reduce content (oh, yes, please, we’re not even exactly sure how much redundant, almost identical content we have). So far we’re confident, we’re not only doing the right thing, but doing it for the right reasons, too!


Savings have their own price, of course. Sarah’s survey confirms several cost points we’ve already identified in the project.

  • Converting legacy content is a biggie for us, simply because we currently have a lot of stuff.
  • Redefining output layout will take time, but will be worth it given what Flare is capable of doing with CSS in both web and print outputs.
  • Integrating a new system with its writing and publishing processes into our product and workflow systems will also take some time.


Mistakes have been made by others before us, and we’ll have plenty of chances to make our very own mistakes. If we’re lucky, we can avoid repeating the mistakes of others:

  • Planning and project management cause problems, maybe because most companies lack the experience of major documentation overhaul projects. Sarah specifically mentioned the lack of understanding of the project scope and of the need for testing. So we’ll look through our project plan again and ensure that the estimates are plausible.
  • Converting legacy contents can also get you into trouble, especially when you convert something that’s less than structured. It doesn’t help if you reserve too little time to do it or get inexperienced people to do, whether it’s off-shore labor or student helpers. That’s sound advice: GIGO (“garbage in, garbage out”) can certainly endanger the expected benefits. A new tool can help us be more efficient, but we still have to learn and apply structured writing in topics. So this confirms one of my two tech comm dogmas: Don’t get a new tool to fix your processes!

Setting out

What do you think? Is our crew well-equipped, given a tried and proven method, well-defined processes, a new tool and the words of warnings above? If you have additional advice, please leave a message.

Keeping your documentation stakeholders happy

Don’t forget your stakeholders and their practices as you improve and change documentation. – That was the humbling lesson I learned (once again) as I presented our revamped documentation to non-tech comm colleagues.

Reporting on progress

The company I work for currently moves its documentation towards more structured writing and topic-based authoring. We’ve already rolled out redefined processes and several topic-based user manuals, so it was an opportunity to present to  non-tech comm colleagues what we’d done already, why and how we did it, and what else was in store. I talked about topic-based authoring and how it’s chunked, task-oriented, reusable, and independent of delivery format. Then I talked about the benefits and challenges:

  • For users, topic-based help can be updated more frequently, it is easier and faster to use online, though it breaks the narrative flow
  • For everyone working on our module, it means easier contributions
  • For the company, it allows to leverage* content after one-time migration efforts

* I know “leverage” is not a verb, but there were managers present who love the word… 🙂

I thought I was pretty clever for presenting how cool the new documentation was not primarily for writers, but for users, my colleagues and the company as a whole. And it did go over well on the whole. But there was…

The thing about trains

Person reading by a track in a railroad station

The most contentious issue turned out to be an unexpected use of the documentation: Current user manuals sometimes contain flowing prose walk-throughs of sample setups with many screenshots. When they are written well, they are nice to read. And allegedly users like to print out the PDF files and read them on the commuter train.

The problem of prose

There are several problems with the narrative manuals for users:

  • They are hard to use and search in, unless you want to know exactly the one thing they are describing.
  • Any sample setup is bound to miss what they need by a little or even a lot, because our product is highly configurable (you can even customize field names in windows).

There are problems for writers as well:

  • The prose is really hard to update when functions or processes change because the narrative flow may require small or large changes in several places.
  • The screenshots take longer to update and localize than mere text.

I gave these reasons, invited colleagues to check out the manuals done in the new fashion and cited survey findings that most of our users consult the documentation when they have a specific problem, though very few actually read manuals end-to-end.

But the ultimate lesson for me was that I could focus on our mission all I want, I also need to address the change with my stakeholders not only in rational terms, but also in terms of their habits and expectations.

Your turn

Do you think the customer is always right, even if he asks for documentation that is harder to maintain and harder to use in most cases? How can you promote change among stakeholders which you are sure will benefit everyone in the long run? Please leave a comment.

How to convince managers of topic-based authoring, part 2

To get managers behind a migration to topic-based authoring (TBA), focus on benefits and savings. This is the last post in a two-part series. Find the beginning and background in part 1.

I present the speaker notes and explanations instead of the actual slides which only contain the phrases in bold below.

Benefits and challenges for writers

Make documentation efficient. For technical writers, the structure within topics and across all topics makes writing topics more efficient because you spend less time stressing over what goes where and over layout.

Make documentation transparent. The structure of the topics collection as a whole makes content more transparent: It’s easier to spot a missing topic, if each setup procedure (how to set up stuff) is accompanied by an operating procedure (how to use what you’ve just set up) and by a concept topic (what is that stuff you’ll set up and operate). Thanks to their structure and smaller units, documentation efforts also become easier to estimate – though maybe more tedious to report on in their details.

Collaborate more easily. The structure also makes it easier and faster for writers to collaborate on writing, reviewing and editing each other’s topics, again, because it’s quickly obvious what belongs (or is still missing) where.

Assume new tasks and responsibilities. Challenges for writers are learning a whole new range of tasks and responsibilities, from “chunking” subjects into topics and making sure there is one (main) topic for each subject to interfacing nicely with the topics of colleagues to peer-editing other people’s topics. On the other hand, most writers no longer have to double as layouters and publishers, since that role is usually in the hands of a few people.

Migrating legacy content. Another challenge is, of course, to migrate all existing contents into topics. However, this is a one-time effort, while the benefits of clearly structured topics keep paying off.

Benefits and challenges for companies

Of course, the benefits and challenges for writers affect the company as a whole. But there are additional effects to the company owning topic-based documentation.

Leverage corporate content. Cleanly structured (and tagged) content in topics is much easier to leverage as part of a corporate content strategy. (Did I mention this was a presentation for managers? Hence the verb “to leverage”…) After all, there are other teams who may well hold stakes in some documentation topics or parts of them:

  • Product management or even Marketing may want to reuse parts of concept topics, such as use cases.
  • Training could reuse procedural topics.
  • Quickly searchable documentation can improve customer services – or any type of performance support your company may offer.

Make recruitment more efficient. Clearly structured, topic-based documentation will make it easier on a company to find and hire professional, qualified technical writers – and help new writers get up to speed faster.

Savings from topic-based authoring

Your mileage will vary, depending on your current deliverables, processes and tools. However, from the case studies I’ve seen around the web and at conferences, our numbers are not unusual. Savings are in hours for writers who apply topic-based authoring compared to their earlier efforts without TBA.

  • Writing Release Notes as usual – saving 0%
  • Writing Online Help, largely reusing Release Notes topics – saving 45-60%
  • Writing new User Manuals, by reusing some topics from Release Notes or Online Help – savings unknown
  • Updating existing User Manuals, by reusing Release Notes topics – saving 60-75%

Complementary information

To read more about measuring efforts and costs, see my previous posts about:

About topic-based authoring, I recommend these two books:

Your turn

Would these arguments convince your managers to support you in moving to topic-based authoring? What other arguments might it take? Should such an initiative to restructure documentation come from writers or managers? Please leave a comment.

MadCap roadshow in Long Beach

MadCap kicked of the 2011 season of roadshows on March 13 in Long Beach, CA, to coincide with the workshop day of the WritersUA conference.

A full-day program offered primers on topic-based authoring and single sourcing, best (and less recommended) practices of collaborative authoring, and a passionate introduction to Cascading Style Sheets (CSS). Shorter breakout sessions (which don’t seem to be part of the other roadshow dates) presented tips and tricks for Flare: How to handle tables, create print output and localize, as well as a case study about moving from RoboHelp to Flare.

Mike Hamilton at the MadCap roadshow

Mike Hamilton reminds us to think topics!

More like a conference

Several aspects made the event feel more like a Flare-centric conference than the marketing or sales event it was as well:

  • Presentations address tech writing challenges in general, whether or not you use Flare:
    • How to optimize topics for reuse
    • How to efficiently publish to several media from one source
    • How to collaborate with other authors.
    • And, oh yes, how you can do these things with Flare. But the general emphasis was on: “Here’s how you can work efficiently.” In fact, the helpful introduction to CSS didn’t rely on Flare at all. The more sales-y “Wanna see what the new version can do?” came only in a longish rock video with MC Mike during the drinks reception.
  • Networking opportunities galore during breakfast, lunch, the concluding reception and to some extent even during the breakout sessions.
  • A day’s worth of Q&A. MadCap brought more than a dozen people from all teams to be able to answer any question that we present and future users might throw at them. Their answers were usually constructive and frank, though my question about the number of employees got the PR-tinted answer “fewer than 100”. When asked whether Flare can do X, Mike sometimes says: “Not at the moment.” Previously, I thought this was just supposed to sound better than “No.” But after following Flare’s development for a few versions, I now see that many of such features have been added, such as the long-awaited formula capabilities in version 7.

Taking tech comm seriously

In a nutshell, MadCap continues to take tech writers, their requests and issues seriously. Here are some examples of insights from the sessions to illustrate how they go beyond the bells and whistles of selling a new version:

  • Customer focus is important – but documentation must also recognize and satisfy the owner (usually, the company that pays for the documentation) and the manager (who needs to ensure that documentation is completed in time and in budget).
  • Create separate target definitions for separate deliverables. Don’t rely on manual steps in the production process which might get lost in the hustle and bustle. For example, don’t trust that you’ll remember to update the global variable with the correct company name…
  • When you share source files over a network, even in a small team, use either a dedicated source control system or SharePoint (which includes source control) which avoids two people editing the same file at once and allows to lock down central resources like stylesheets.
  • There is no one font size that’s always appropriate. How large a font appears depends a lot on the “x-height” (roughly the height of the letter x), and that can vary in fonts of the same size.

Wish list

Taking my cue from other conferences I’ve attended, I think MadCap could add two things to improve the roadshow:

  • Book table. There are a few books available about MadCap products. For those of us who like books with their tools, why not have at least a sample copy by the registration table, so we can check them out whether we want to buy them or not?
  • Rant & rave session. This one might not be in MadCap’s best interest, but hey, they’re generally a pretty accessible company who like to collaborate with their customers and prospects. I think they should put on a session where attendees can get one minute each to rant and/or rave about the products. Such a forum would give MadCap a quick way to see what bothers a lot of users – and what they like. Two peeves came up:
    • The previously free reviewer module “X-Edit” has been replaced by “Contributor” which requires a license per user. This is not feasible in environments where each writer easily has one or two dozen potential reviewers. MadCap needs to come up with a better licensing model for this.
    • Flare lets you define separate CSS Mediums for print and online in great detail. A field near the top indicates which one you’re editing. Yet a lot of users still manage to edit the “wrong” one when they get all engrossed in styles. Simply highlighting this better would improve usability for focused, single-minded users.

If you’ve attended a MadCap roadshow or other such industry event or are considering to attend, feel free to share impressions or questions in the comments.