Migrating to a Structured Standards-based Documentation Solution

Read time: 8 minute(s)

Potential clients come to this world of structured content authoring from two main sources:

They are starting fresh and after a little bit of comparing between structured and unstructured editing, between opened and closed solutions and some soul searching they come to regard structured authoring with a specific XML standard in general (and usually DITA in particular) as the possible solution for them.
They are migrating from a previous unstructured or structured solution.

I think people in this second category start thinking about structured writing when they start encountering certain limitations with their current approach. These limitations they experience with their current system could be:

The need to reuse more content.

With structured XML authoring in general and with DITA in particular you have so many ways of reusing content. In a previous blog post I tried to come up with an overview about all the ways in which you can reuse content using DITA: DITA Reuse Strategies
Produce multiple outputs from the same content using some complex profiling conditions which are not supported in the current work flow.
Stop thinking about how the content is styled.

You may want to focus more on the actual content and on semantically tagging it than on the way in which it will be presented in a certain output format.
Publish to more output formats than the current editing solution allows.

Using a widely adopted open source standard like DITA for documentation also means having access to a variety of commercial and open source tools to generate various output formats from it. For example for obtaining the PDF you have about 5-6 distinct possible solutions:Possibilities to obtain PDF from DITA.
Enforce certain internal rules on the documents.

It's hard to impose best practices in unstructured documents. But with structured XML content, you can use Schematron to easily cover this aspect and even to provide quick fixes for your authors: Schematron Checks to help Technical Writing.
Benefit of advice and help from a larger community of writers and developers.

When you are using a closed source solution, you may have only one forum and a couple of people willing to help. When you have a larger community you will be able to reach out with a single email to lots of people, and somebody may want to help you.
Share documentation between different companies.

If a larger company which uses structured writing takes over a smaller one, the smaller company will need to adopt structured writing as well.
Own your content.

Some editing solutions are closed source, you are forced to use a single tool because there are no other tools being to read that format. Then you need to ask yourself the question: Is this content actually mine?
Problems with your current tool vendor.

If the format is closed source and the tool vendor is not responsive to your needs, you need to somehow move your content over to a market with multiple tool vendors available because competition also means smaller prices and better customer support.

Switching to structured content writing also has its problems. And I think the main ones are these:

The people. The fact that we all are reluctant to change. The learning curve. Writers might need to re-learn how to structure and write their documentation. Besides the technical aspects they will need to learn to divide content in small modules and to reuse parts in multiple places. Writers may not be willing to do this. We usually are very reluctant to change tools if we do not see instant benefits deriving from it.
Effort to convert the current available content to structured content. You can either choose manual conversion or automated conversion or in most cases a mixture of the two. Conversion will never be perfect, you will still need to go through the entire content and re-structure it taking into account module-based editing.
Customize the obtained output format. You may get out of the box various outputs from your content but you will always need to customize it to adhere to company standards. If you are using the DITA Open Toolkit for publishing you will need basic XSLT development skills to customize the PDF and CSS skills to customize the XHTML based output.
Money. You need to spend more money to get new tools, possibly a new CMS. Although I consider that starters, for a pilot project DITA does not need to be expensive. Here's how we're using DITA internally for our user's manual: Collaboration for Documenting a Software Product using DITA.
Sometimes you might need to control the styling of your obtained output so much and it would be impossible to separate the styling information from the content.

So can we draw a conclusion from all this?

Well, maybe not everybody interested in structured authoring will succeed to convert to it. But I think that one thing will hold true in most cases:

Once you convert to structured content, you will never go back.