Tag Archives: DITA

The number of companies using DITA – a story of success or failure?

Posted on by
3

It’s been seven years since DITA (Darwin Information Typing Architecture) became an open standard. DITA, for those that don’t know, is an XML-based standard for structuring, writing, managing and publishing the type of content that you’d typically find in user guides, online Help and other technical documentation.

Recently, the DITAWriter web site researched how many organisations use DITA today. It found 372 organisations worldwide using DITA, and it also reported that 4% of technical writing job vacancies listed DITA as a required skill. The web site concluded these figures were a sign of the growing success of DITA, whereas others took the opposite view.

So where does the truth lie – is the adoption of DITA a story of success or failure? The answer lies, perhaps, within the laws of economics.

Continue reading →

How much content can you actually re-use when you move to single sourcing?

Posted on by
4

One of the challenges when considering moving to a single sourcing authoring environment, such as DITA, is determining the Return on Investment. This often boils down to a key question: how much content can you actually re-use?

Organisations typically attempt to answer this question in a number of ways:

  • Conducting a semi-manual information audit of the existing content to identify the number of times the same chunks of information is repeated. Unfortunately, this can be a large and lengthly exercise.
  • If the content is translated, getting reports from Translation Memory tools indicating where content might be repeated. Unfortunately, if you’re not translating your content, you won’t have this information.
  • Using benchmark industry measures. Unfortunately, these can vary enormously (from 25% to 75% content re-use), and your situation may be totally different.

In an ideal world, you’d be able use an application that could look at all your content and give you a report telling you the where content is repeated. It could do the “heavy lifting” in the information audit automatically for you. This programmatic analysis of reuse within existing content, at an affordable cost, is now starting to become possible.

Continue reading →

The federated Help authoring system

Posted on by
1

The federated database is a term that has been growing in popularity in recent months. According to Wikipedia:

Through data abstraction, federated database systems can provide a uniform user interface, enabling users and clients to store and retrieve data in multiple noncontiguous databases

Could a similar approach be used in the field of technical authoring – could we have federated Help authoring systems?

There’s a number of situations where a federated Help authoring system might be needed:

  1. A company is selling a system that includes products from other organisations. For example, a telephony solution might include handsets supplied from a third-party manufacturer. This systems integrator is likely to want the handset manuals to use their product name, “look and feel”, contact details and company logo.
  2. Another subsidiary or department is creating documentation in their own Help authoring system, and you need to include some of their content in your user documentation. For example, these could be Knowledge Base articles created by the Support department, or embedded Help written into the application screens by the programmers. They cannot or do not want to use the same authoring system as you, and you don’t have the authority or desire to enforce your system on them.

There are a number of ways a federated Help authoring system can be set up:

  • One is to agree a common data structure. You could require your suppliers to make their user guides accessible in DITA format (instead of, for example, InDesign). You would need to define which text you wanted to be conditional – such as the company name, product name and contact details. In a federated model, their content would stay in their system, but could be integrated with your content when you generate the user documents. This means if they updated the manual, these changes would appear in your system.
  • Another approach is to simply have the content as an embedded object in your authoring system. You would need to get your colleagues to create content where the formatting information was not embedded with the content itself, and again you’d need to agree which text you wanted to be conditional.

The attraction of this approach is it minimises the effort required by the other writing teams, and it provides a solution where you don’t have the ability to establish a single authoring solution.

If you’re doing this today, feel free to share your experience.

The DITA XML authoring barrier for non-Technical Authors

Posted on by
3

One of the challenges for organisations moving to a new content management system for their user documentation is selecting an authoring tool that is:

  • powerful enough, and
  • can be used by non-Technical Authors as well as the professional Technical Authors.

Many organisations want staff, such as developers, to be able to add content to the system directly – without having to pass it over to the Technical Publications department. The difficulty lies in that many tools for authoring in DITA and other XML schemas are daunting to those unfamiliar with the underlying principles of DITA and structured content. It’s even more challenging if you’re someone who is only going to write content occasionally.

One approach is to create templates, with defined fields that need to be filled in. Another is to get staff to write in Word, again in conjunction with a template, import the text into the content management system and then map metadata and other semantic information to the content at that stage.

Is it an unsurmountable problem? Should we just accept that writing semi-structured XHTML content (such as wiki-based content or WordPress-like authoring environments) is a better compromise? What you lose in modularity, you gain in having an easy-to-use authoring environment. Alternatively, do we need to recognize we’ll always need specialists who can convert text into the appropriate format - the equivalent of the typing pool or typesetters?

It has bearing on the role and value of Technical Authors. Is it their main value in writing skills, information management skills, editing skills or in using a specialist tool? If the organisation believes “everyone can write well”, then is their value in using software that’s complex and tricky to use?

Upcoming Cherryleaf events during September and October 2012

Posted on by
Reply

Here are some upcoming Cherryleaf events during September and October 2012.

Our Q4 Trends in Technical Documentation talk

The Lean User Manual: Using Lean principles in Technical Publications

  • 20th September 2012, 09.30-12.30 Free

Dr Tony Self’s DITA training courses in London

Publishing with the DITA Open Toolkit

  • 8 October 2012

DITA authoring best practices

  • 9 October 2012

Dr Tony Self’s DITA training courses in London

Posted on by
Reply

We’ve arranged for Dr. Tony Self to host his DITA training workshops in London this October. Tony is based in Australia, and he also known as “Dr. DITA”, as he has a PhD in DITA. He is also the author of “The DITA Style Guide”.

Publishing with the DITA Open Toolkit, 8 October 2012

Most DITA implementations start with the DITA Open Toolkit (OT) being used for publishing of DITA content. The Open Toolkit is developed and managed separately from the DITA standard itself, and provides an open-ended collection of tools and sample files. Although some DITA tools provide alternative publishing paths for DITA content, many DITA authoring tools rely on the OT.

In this workshop, you will learn how to install, configure, test, customise, and publish DITA documents using the DITA Open Toolkit. Along the way, you will discover why the OT appears to be complicated and quirky. You will also learn its relationship with DITA, and how it is typically integrated with a DITA authoring tool. The OT’s command line publishing interface is quite daunting for many, so you will also discover how the free WinANT Echidna tool can provide a friendly, feature-rich interface.

We will work hands-on to explore how to provide customised PDF and HTML output and corporate “badging” of output. A number of third party plug-ins extend the functionality of the OT further, and we will also experiment with some of these useful extensions.

DITA authoring best practices, 9 October 2012

As more companies implement DITA to streamline the development of documentation and user assistance, best practices for DITA authoring are being established. While the OASIS DITA standard provides rules for the use of elements and attributes, it does not provide clear guidelines for how to practically apply the mark-up, and how to create consistency so that DITA documents can be more readily interchanged. DITA has the potential to change habits of composition, expression and presentation for a broad range of writers and in so doing enhance productivity across a number of industries and occupations.

Adopting best practices will enable authors to maximise their productivity. In traditional authoring, best practices are often captured in a style guide, providing real-world examples and clear recommendations. However, existing style guides are written for style-based authoring, and not for DITA’s semantic mark-up approach. Tony Self has analysed the way in which DITA has been used, and has developed a DITA Style Guide to fill the gap between the DITA standard and traditional style manuals. In this workshop, Tony describes what constitutes best practice in DITA, explains the rationale behind the commonly used DITA elements and structures, and works through practical examples of best practice decisions.

The workshop will also cover the basics of DITA authoring. It is aimed at authors new to DITA and experienced authors wanting to improve their practices.

Cherryleaf XML DITA workshops October 2012 – your opinion needed

Posted on by
1

We’ve arranged for Dr. Tony Self to host a few training workshops in London this October. Tony is based in Australia, and he also known as Dr. DITA, as he has a PhD in DITA and is the author of The DITA Style Guide.
http://www.scriptorium.com/books/the-dita-style-guide-best-practices-for-authors/

We’d love your feedback on which XML and DITA training courses we should offer:

  • Should we offer an introduction to DITA, or is everyone now familiar with it?
  • Do you want to know more about publishing from XML?
  • Is there an aspect of XML and DITA you’d like to know more about
  • What course would you want to attend?

Do let us know!

Any user guide, as long as it’s black

Posted on by
2

At last week’s UAEurope conference (and in this season’s Communicator magazine), Dr. Tony Self suggested how car manufacture can be an allegory for the technical communication profession.

Henry Ford revolutionised car manufacture when his production line replaced the method where cars were hand-made by artisans. Famously, Henry Ford offered the Model T in “any colour… so long as it is black”.

There are parallels in technical communication. Many technical communicators are still clinging to hand-crafted documentation, creating custom layouts and “tweaking” formatting, when new modular methods are vastly more efficient. The age of offering documents in any “colour” the customer wants is over. And just as car manufacture has long since moved to automation, technical communication too must embrace automation, with XML providing the technology platform to make this possible.

I think there is even more we can learn from car manufacturers.

While the Model T was initially a success, Ford was slow to replace it with a new model, and by 1930 the company had been overtaken by General Motors. Ford, had, in effect, created a very efficient process for creating something that almost nobody wanted.  The process was inflexible and it took them a year to introduce the successor, the Model A. So perhaps, technical communicators need to make sure what they produce efficiently is what their customers actually want.

In addition to learning from Alfred P. Sloan (the head of General Motors at the time), we can also learn from today’s car manufacturing processes. Today, many manufacturers use Lean manufacturing. Lean focuses on stripping out waste – if something does not add value to the customer, then it is eliminated. In other words, Technical Communicators need to quantify and demonstrate the value of their documentation to the customer, if they want to use car manufacturing as their model for the future.

So what is Single Sourcing and what is DITA?

Posted on by
1

Single Sourcing reduces the need to create and maintain duplicate content, by enabling you to use existing “chunks” of content. This means you can have the same information in different publications, and you can have a library of existing content to re-use when you’re developing new documents.

The content is stored independently of the formatting, the same content can be published to different media. These can be used many times to generate paper manuals, Web pages, online Help and e-learning material.

Single Sourcing can significantly improve the way you create, develop and maintain content.

What is DITA ?

DITA is an increasingly popular open source XML-based framework for designing and delivering well-structured technical documentation efficiently and consistently in a single-sourcing environment. Cherryleaf can help you understand when, why, where and how to use DITA.

The infinitely reusable document

Posted on by
1

Alongside Education and Publishing, Design is a profession from whom Technical Communicators can learn a great deal. The BBC TV series, The Genius of Design, looked at new trends towards green, “cradle to cradle”, design, where components in objects are designed to be capable of being stripped down and reused infinitely.

I’ve never head anyone talk of an infinitely reusable document, but that is, in essence, where we are heading with DITA based content. DITA offers the promise of being able to reuse topics over and over again. Unless the content becomes irrelevant or incorrect, that is.

So can technical authors apply the concepts of “cradle to cradle” (C2C) to its profession? It might offer new and useful ways to explain the value of DITA based authoring.