24 | 10 | 2014

How DITA Can Help Even the Smallest Businesses

One thing you must negotiate about with your technical writer is the format in which the writer delivers the documentation. There are numerous options MS-Word will, for many businesses be the defacto standard as the Office Suite will be available in most businesses. However, the use of character and paragraph formatting will vary from writer to writer. This does have an impact on how much time you need to bring the document under your control for publishing.

Many writers use Adobe FrameMaker, especially if that writer supplies to a larger company. Using Adobe FrameMaker is costly at the beginning. Once the use of FrameMaker is established, it has many advantages of just another wordprocessor. For one, FrameMaker has much better control over templates and layouts.
But, the writer is not alone. How about editors, translators and printers? You may agree with your writer that the document is delivered in a specific format, but the editor or translator may not have the same preferences as to how to use specific settings of the software. So, even though you are clear about what software to use and what format still the look of the document may take a lot of time to fine tune.

If the client can step away from the specific choice of software and layout, but instead focus on the content alone then production of a document looks much simpler. The writer can concentrate on the effect of the content, the editor on correct spelling and the translator on the language differences. Finally, when it is time for printing content and layout are brought together. You can leave the layout of the document to one person, a specialist.

That scenario is not wishful thinking. With the use of XML it may be possible. With the XML based DITA standard it is possible.

 

The Use of DITA

When I first read about DITA, I wondered why the creators called the standard Darwin Information Typing Architecture?

The Information Typing part is quite clear. DITA is an XML language for typing information, especially technical information. Typing in this context is not using a keyboard, but specifying what the purpose is of  the text your are writing. For example, most technical writing is about giving an explanation of a concept or giving an instruction for a task. Now, when you are explaining a concept, you can type the text as concept. When you are writing an instruction, you can type the text as task. Task and concept are actually two possibilities for a topic as defined in DITA. It goes to show that for technical writers DITA comes as a very natural XML language.

The Architecture you will find in the underlying knowledge of how technical documentation is produced, from authoring to publishing. Since nowadays there are numerous ways to author or publish, a universal or XML language must either work without assumptions about authoring and publishing; or be quite explicit about it. DITA takes the position that it is quite explicit about its assumptions of how a technical document is produced, specifically that the layout is separate from the content and that the content should be re-usable in different documents for different purposes.

In DITA you will – in contrast to general document creation tools such as MS-Word, OpenOffice and the like – not find the topics collected in a hierarchy. To explain, in general word processing documents text resides in paragraphs that are collected in chapters that may be part of a section and eventually the sections make up the document or book. Instead, the highest level element in a DITA document is the topic. The document itself does not determine the order of the topic nor how the topics are collected in chapters and books. How topics are collected in chapters and books is determined in a second DITA document type, the DITAmap.

In DITA, authors – multiple authors, distributed authors, theoretically anywhere in the world – work on individual topics and an editor collects the topics he needs for a specific purpose into a book using a map. The editor can reuse topics in different books. The editor can receive completed topics and forward them to translators. This is usually done in a content management system, which eventually helps to publish the material. The architecture makes sure this is all possible. The content is written in small documents, that are easily sent around and only at the last time they are collected into big documents for publishing.

But the Darwin part? In everything I read about DITA, the authors do not explain why the name Darwin is used. But, Darwin had something to do with evolution and the origin of species. DITA as it happens is not an XML language that is carved in bedrock. For different purposes the definition of the meaning of a document part may be redefined. For example, text in a Question-and-Answer file is either a question or an answer. In a task you at least have a part that contains the ordered steps of the task. So, for each purpose you can specialize the definition of the topic to create the best fitting definition. That is evolution, survival of the fittest. Still the architecture and standards of DITA make sure that the publishing tools can still understand what the tags mean and thus can always publish the DITA document, the tags used can be specialized for the kind of technical information you want to have published.

Say That Again?

By now you feel already that there must be some advantage for you to use DITA in technical information. Whether it is training or plain product information, DITA is applicable. DITA has big possibilities for application in any company.

DITA separates content from layout. The writer supplies the content without any layout features that may change along the way. Instead, the writer has supplied text and indicated with tags what is meant with the different pieces of text.

DITA can be specialized. As a client of an author, you want to see specific content in the document. If a task must be described, you want to see an explanation of the goal of the task, what needs to be done before the task is executed, then you want to see numbered steps and finally you want to see how the task is finished with a quality check or a clean up. You can use a standard definition of a task that contains most of those elements, but you may also create your own definition for the special situation your company is in. Using that standard, all authors that supply to you provide similar information the same way each time they write a task for you.

DITA comes natural for technical writers. Technical writers specialize in the effect of language on a reader, they know how to write. They also know that each part of a text has a purpose. Identifying the purpose of the text with a tag is thus only normal for technical writers. The structure of the DITA definition helps the performance of the technical writer.

DITA is a standard adopted by some of the large companies. You may, as a small to medium company, benefit from the availability of the same resources as the big companies.

So, What Does That Cost?

Large companies already know DITA. This has made sure that a big variety of software exists to author, edit, translate and print DITA documents and maps. DITA software is available from almost free to very-expensive-only-for-enterprises cost. Because DITA did not yet perculate into the smallest companies, there are no completely free and fully functional solutions.

To author a DITA document XML editors are often used. You feed an XML editor with the definition of the elements you want to use. Then the editor will make sure the writer writes only documents according to the definition. Yes, free XML editors are available. Although the free editors give you a good taste of the XML Editor, the free editor misses some functions the life of the writer a lot easier. Then the editor suddenly costs a few hundred dollars.

DITA plug-ins for MS-Word also exist. These plug-ins ensure that the document you write complies to the defined standard in the comfortable environment of the Office Suite. I have not used such a plugin, and I am biased considering Word plug-ins. In the free world of MS-Words, plug-ins are an unnatural constraint on how you work in MS-Word. Considering that such a plug-in may cost almost the same as an XML editor, I lean towards XML editors.

Then there is FrameMaker. FrameMaker is a nice tool to work with, very solid, very precise and with a big established community. FrameMaker is more or less expensive to start with and then you don't have the add-on needed to write DITA documents. Great tool, with an accompanying price tag. Your writer may already have FrameMaker as part of his service because it is a well-known tool in the writing business.

Do you need a Content Management System for DITA? If you send the documents around from authors, to editors, to reviewers, to translators and the printer; then you will eventually need a Content Management System. Content Management System control the flow and make sure everybody who needs to be involved will be involved. Content Management Systems come almost free as OpenSource software. Then there are the SharePoint applications that make use of your existing SharePoint installation. At the top of the market are the systems that cost more than $100,000.

A Content Management System is not needed if your published document is small and the amount of files is manageable for one person. But, let me warn you. In a project of four weeks one author can write more than a hundred DITA documents, easily. To manage all those files and make sure they are all used, and you do not loose track of the documents you did not link in a map, you may appreciate some help.

How to Benefit From DITA

To benefit from DITA as a small to medium sized company, do the following:

  • Jump into DITA whole heartedly. Standardization is about embracing the standard. If you think you need a way back, you better stay with MS-Word. Think standard.
  • Buildup your documentation processes. You will need to find a way to find and select writers that you are comfortable with. Because the writers will supply in a standard way, your writer may be anywhere. On the other hand, you will also need the tools to manage those writers.
  • Align the documentation with your customers. You now have the tools to make documents for specific customers and readers. For example, up to now you only provided one document to your customer because that was easier to maintain. Now you may want to provide one document for the purchaser and another for the engineer. Because content and layout are separate you may supply customized layouts to your customers for easier integration in their documentation.
  • The financial benefits are twofold. You can use vary between cheaper writers (for straight forward texts) and more expensive writers (for high quality texts) while still receiving and publishing the documents the same way. The influence of each individual writer is smaller, as long as the writer can deliver standard compliant documents. On the other hand, you customers will like the greater flexibility you have in supplying documentation with your product.

References

WikiPedia is of course a good starting point.
    http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture

An excellent overview of what DITA is from the people who created it:
    http://www.ibm.com/developerworks/xml/library/x-dita1/

A good, but brief and somewhat dated overview of the tools available for authoring DITA:
    http://www.ditanews.com/tools/STC_Intercom.pdf

You should know what content management systems can do for you, with DITA you will use a Component Content Management System and don't confuse them with web content management systems
    http://en.wikipedia.org/wiki/Content_management_system

And the people who created the DITA standard: IBM
    http://www.ibm.com/developerworks/xml/library/x-dita1/

If you need to know something about XML:
    http://webdesign.about.com/od/xml/a/xml_content.htm

And, of course, a reminder that it doesn't have to be DITA:
    http://www.author-it.com/blog/2010/01/13/whats-stopping-the-wider-use-of-dita-within-your-company/

Strategy

I believe that thinking about strategy can help your business. Building a strategy helped me and the principals I used can readily be used for your business.

Readmore

Documentation

Good documentation helps you run your business. Documentation is a valuable asset when written well and read often. Albert Zuurbier helps your business word for word.

Readmore