DITA without the DTD

A couple of months ago, I led a training course in DITA XML. The first two days were stock slides, concerned with the DTDs, conref and conkeyref mechanism, then, the third day, the one I wrote, was entirely about the DITA philosophy, the semantic nature of the DTDs, progressive disclosure and writing great short descriptions (shortdescs).

Rupert the bear providing progressive disclosure

More recently, I've been asked to use Adobe Technical Communications Suite (TCS 3.5) to create content. As for previous assignments, the current documentation is unstructured, does not reuse content, and the help and PDFs are not  single-sourced. That is, the help systems are entirely separate from the PDF and content is copied between the two. I'm assuming this is reasonably common. The team members are all professional writers of a certain quality but, outside of word choice and a few style guide rules, the content varies quite considerably in approach and overall style.

For my part, and probably from my long term exposure to DITA XML, I have adopted many of the writing philosophies that it provides and I work them into my normal output. For instance, progressive disclosure. If I am writing an introduction in a chapter, I don't write, "This chapter tells you about..." and list the subjects, I write a summary that includes high level facts from the subject matter and let the reader make the assumption that this is the subject of the chapter.

Then it hit me, why not formally introduce the writing rules of progressive disclosure and short descriptions into the current writing guide. Why not aim for a DITA-like layout in tasks? Why not, as a team, plan the information set with Task, Concept and Reference topics as if we were using DITA. The double-benefit of this approach is that it results in more consistent documentation, and, should the decision be made in the future to move to DITA XML, we have topics that are ready for the transition.

Second guessing what the user needs

I often say that my job is to be an advocate for the user within an organization. I shouldn't just document the tasks that the user wants to achieve, I should also push back to the development team to explain when the software presents barriers to achieving tasks.

However, how do we know what real users are trying to achieve with the software? We can make a best guess based on previous experience but, new features are new features and don't necessarily have a precedent. What then?

I've heard it said several times recently that we should be writing the bulk of the user documentation after the product is released and that we should base the tasks we document on needs identified from technical support calls.

Indeed, several large companies are already doing this.

Skype online help

This has parallels with the release early and release often of Agile and Scrum software development where features bubble to the top of a list. I get the feeling that post-release documentation will be the hot topic of 2012.

Nobody's talking about it

The circles I move in so far aren't considering the implication of the movement of English language technical communications to lower-cost India. However, in the UK there has been a dip in contract rates and writing rates have remained more or less static for perhaps 10 years.

The list of panelists from the tcworld India 2012 conference makes interesting reading:

1. Ken Chu, Senior Director of Information Development, Server Technologies, Oracle Corporation, USA
2. Suneeta Aggarwal, Director of Technical Publications at TIBCO Software Inc, USA
3. Sonali Natarajan, Director of Documentation, Cisco Corporation, USA

So Oracle, TIBCO and Cisco now write their content in India do they?

I read a while back that by working with India from the UK, both economies would grow. If that is true, what we need to do, rather than burying our heads in the sand, is embrace that idea and start working together.

For many businesses in the UK, success can only come by working in the team with the developers and engineer subject matter experts (SME). Writing requires understanding and expertise but, which bits of the process could you share with a lower cost colleague? How does your organization aid you in forming those relationships? It's time to start thinking about these issues.

Test Driving the Componize DITA XML Solution

Componize kindly granted me a trial of their Componize Cloud-based system. They sent me a very nice Getting Started email and a password reset.

The Componize user guide, Getting Started topic (requires trial login) looks like the Eclipse Help output from the DITA OpenToolkit. The user guide didn't immediately say how to check-out, modify and check-in content but that's OK because, once I located the DITAmap and topics, I could easily click the "Edit online with DITA Storm button" to open it in a new browser tab.

The following sections describe my first attempts to use Componize with DITA XML content.

First: Change some content

1. Click the My Home link at the top left.
2. In the Alfresco Explorer, drill down to locate the content.





3. Click the Edit Online with DITA Storm button.
4. Make some changes and click Save.

But that isn't really appropriate for a multi-user environment. What we really need to do is check-out, change and check-in a file.

To check-out, change and check-in a topic:

1. From the drop-down, select Check Out, select a location for the working copy, and click Check Out.
2. This creates a working copy.



3. Edit the working copy and click the Check In icon.

Second: Publish

1. In the Alfresco Explorer, navigate to the DITAmap.
2. Click the drop-down and select Run Output Processing.





3. Select the output format (pipeline) you want, and click Add to List.
4. At the top right, click OK.

The screen refreshes surprisingly quickly to show Log files for <ditamap> with the result clearly listed under Results Document with the correct time and date.

In the trial the PDF displays using the default DITA OpenToolkit appearance with my changes included.

My Author-it Elevator Pitch

When you choose Author-it you are choosing

• Single Sourcing,
• Reusable content,
• Modular Writing,
• Assembled Documents
• and Content Management.

Why does Single Sourcing make sense?

Well, Author-it publishes to Print, Web, and Help formats and, given time and budget, you can customize anything and everything you want about those outputs. But what it means on the ground is that you are not writing in any one of those outputs using specific tools and creating independent formatting. In the old world order you’d use Framemaker for print, Robohelp for help, and Dreamweaver for online. You’d spend time formatting and carefully laying out the content in each of those tools. Estimates vary but authors can burn between 40% and 70% of their time making changes to the pagination and formatting of their documents. With single-sourcing that effort is made once up-front. The authors simply need to apply the styles to their content and the formatting looks after itself when you publish - BANG - you’ve now got half the work to do.

Why reuse content?

Look at it like a translation job. You might think that translation at 7 pence per word is expensive. How often do you stop to think what it costs to write the content in the first place. Can you put a value on that, per word? When you include all the research, reviews, editing, and updating, all the emails and coffee breaks, my back of an envelope calculation gives (100 page manual = £7000, Average 200 words per page, 7000p/200 =) about 35p per word. I’ll leave you to join the dots on this one... let’s just say that reusing chunks of text makes sound economic sense and with Author-it it is SO easy, particularly if you invest in Author-it Xtend which brings reuse to the paragraph level and creates consistency on a whole new level.

Why write in a modular style?

A friend of mine, John (@jashw0rth), hit the nail on the head for this one. From being tiny, we’ve been raised with books. The thing about a book is that it reveals information bit by bit. When, as an adult, you start reading manuals in order to do your job, if the information you need isn’t on the page you’re reading, you’ll trust it to be somewhere in the manual. You might keep reading or use the index or table of contents to locate it (or for online manuals, search the PDF). You don’t notice the extra effort because you’re conditioned to it. Now, if you practice chunking information into topic based modular documents you’ll quickly get into the habit of making sure all of the appropriate context is present in the topic or chunk and of providing links to the information that isn’t immediately available. When you then publish those topics to a print format it just makes a noticeably better document. The information you need is there when you need it. You no longer need to trust it will be there somewhere. The message is that we need modular writing for online help and hyperlinked formats but it even makes better printed documents.

What are assembled documents?

Once you have your information in topics you can quickly and easily, drag and drop topics to rearrange them into books for help systems, books for manuals, books aimed at different audiences or products. Assembled documents are another great way of reuse. You can reuse the same content across products or product versions without doing additional writing.. remember that figure of 35p per word?

What about content management?

I’m not going to pretend that all of this comes without a cost. You’ve got to learn a tool. You need to move your existing content into the new tool. You have processes; what will become of them? Author-it is a content management solution. It does help you manage your content. You can search for any text, title, release state. You can search by folder or by book. You can search and replace text in the results (I’m not sure if that’s a new feature but it is very cool). You can use the release states to mirror your processes and formally lock topics that are being reviewed or have been approved. You have that level of control. You can turn on history and store every change that’s ever made to an object, and revert them when you need to.

All of the management, security, and tracking tools that you get with a CMS like Author-it just aren’t available if you’re using file store or code control. And don’t worry, if you’re a small team or excessively paranoid, you can turn them all off... Or on as you prefer.

You already manage your content, why not use a modern tool that is designed for the job to help you?

Did I mention collaboration? 

No, but I’ll end there, thanks for giving me your eyes.

So that’s it, just to recap, Author-it offers;

• Single Sourcing,
• Reusable content,
• Modular Writing,
• Assembled Documents,
• Content Management,
• And collaboration.