JANG F.M. Graat

Geeks don’t sell DITA

Jang F.M. Graat is an independent tech writer, trainer and consultant living in Amsterdam, Netherlands. This talk was created for DITA Europe 2009 in Munich, Germany.

Hello,I’m Hans

Meet our hero. He is a technical writer at a medium-sized company and takes his profession seriously.

I’m the Boss

This is Hans’ employer. He is a gentle, open-minded man in his early sixties. He has built his business single-handedly and is proud of that.

Hans spends his own money on membership of a professional organization. And now he has discovered something that he has been waiting for a long, long time...

DITA

DITA will solve all the problems Hans has been having in meeting deadlines and keeping the documentation up to date. Hans decides to go to his boss to ask if he can use it.

The Darwin Information Typing Architecture (DITA) is an XML-based method for writing and delivering information in a variety of forms. DITA consists of a Document Type Definition (DTD), which specifies how the elements that make up a DITA document can be defined. There’s also a set of XSLT stylesheets that control the look and feel of the output documents. Writers use the stylesheets in conjunction with an XML processor to convert a DITA document to more usable formats, such as HTML or PDF. Like HTML or other variants of XML, DITA consists of a set of tags. There are around 200 tags in the DITA specification. The tags are easy to understand, and many of them are similar to HTML tags. For example, <p> denotes [...]

GeekSpeak

Hans has no doubt that his boss will understand the benefits of this great new technology. He is really getting into it and gives his boss the short techie introduction to DITA.

DITA ?

XML ?

XSLT ?

tags ?

processor ?

transformation ?

conref ?

Hans’ boss hears all kinds of lingo that he does not recognize. He asks Hans to give him a practical example. After all, he is open-minded and not afraid of change.

<task id="washcar" xml:lang="en-us"><title>Washing the car</title><taskbody><steps><step><cmd>Move the car onto the driveway.</cmd>

</step><step><cmd>Attach the water hose to a spout and pull the free end over to the car.</cmd>

</step><step><cmd>Fill a bucket with soapy water.</cmd>

</step>

SillyGeekSpeak

So Hans comes up with one of the standard examples from the DITA toolkit: procedures for washing the car. Unfortunately, this does not really help him convince his boss...

NOT WORKFirst of all, most people do not associate washing the car with work, or not paid work anyway. You either have your kids do it, or do it yourself and make it fun.

And second, the boss feels that he is being treated like a total moron - he knows how to wash his car, so you do not need to write a manual for him about that.

DITA ?

Hans’ boss feels that Hans has taken enough of his precious time and decides that DITA is not something they should go for. “When in doubt, don’t jump” is one of his mottos.

what went wrong ?

Hans is totally surprised by this, as he was convinced that DITA was the way to go for his company and he expected his boss to see it, too. After all, it is so obvious !

Where’s the money ?

But Hans’ reasons to go for DITA are not the ones his boss is sensitive to. Hans should follow the money and find a way to talk business to his boss and “sell” him DITA.

ROI

Hans learns to think along the same lines as his boss - which means he discovers the magic acronym ROI. This is vital to any change in any organization.

So Hans starts reading up on financial aspects of business and finds business cases for DITA. Now he has the material needed to convince his boss.

DITA

no DITA

Hans now presents a business case that shows how DITA brings short-term profits with only small investments. These are the kinds of things managers love to hear.

DITA ?

ROI

free extras

saving resources

cutting costs

Hans’ boss gets interested in DITA now, but he has not built his business believing just anyone, so he asks Hans just how such wonderful ROIs are possible with DITA.

First, we need to create a DTD and buy an XML editor. Then we define a specialisation for our company and the translation rules from the standard DITA DTD to ours. Also, we create read-write rules and an XLST file to translate the sources to various outputs. After the topics are defined we create one bookmap for each publication. Using conrefs we can reuse content from one XML file in another. With the XSL-FO that is included in the DITA-OT we can create simple PDF files. To control the process we write ANT scripts and call libraries to include server-side includes. When that is finished, the output can be processed into online help and using XSLT can be made to fit on a PDA screen.

GeekSpeak

Hans feels he has already won and gets all excited about implementing DITA again. He reverts to “geekspeak” and forgets that his boss does not share the same techie background.

DITA ?

Again, Hans’ boss hears too many technological terms that he does not understand. He does not want to take the risk. Surprisingly (or not), he gives Hans another clear “No”.

what went wrong ?

So, what went wrong this time ? Hans thinks about it hard and does not find the answer. After all, he did give a clear business case. So why did his boss back out after all ?

he just doesn’t see it

Hans feels that his boss is just being blind to all the potential that DITA brings. He seems so open-minded, but he is really too old and slow to understand that he is wrong.

who just doesn’t see it ?

But Hans, can you see that your own preconceptions about technology might not be the ultimate truth - that there are different kinds of truths you can choose from ?

What is Real ?

After all, what is real and what is not depends on how you look at it, right ? You do not need to be Neo to know that there might be different possible views on reality.

Maybe you took the red pill and your boss took the blue pill. And you can discuss who is right and who is wrong for a very long time: that question cannot be resolved.

I’m still the Boss

The bad news for you is that your boss needs to pay for the whole thing, so he is going to be right, even if he is wrong.

So Hans needs to really think about presenting the concepts of DITA to his boss in a language that his boss understands. Use examples from the world in which his boss lives and thinks.

Many machines are built from complex subassemblies, which may vary from one machine to another - his boss does not pay engineers to reinvent the wheel again and again.

So if this is true for all those modules the engineering department is creating and reusing, why can’t this be the same for the documentation department ?

Hans uses the engineering style of his own company to explain what he would like to do for the documentation, using DITA. Document modules and assemble them into manuals.

DITA ?

reuse

ROI

various outputs

higher quality

modular design

Using this strategy, Hans convinces his boss that modular documentation design is not different from modular machine design. This is something his boss can relate to.

DITA ?

Hans’ boss does not need to know technical details of DITA. He just needs to understand the basic concept enough to run a pilot project. After that step, the rest is a walk in the park.

The Future of DITA ?

“All the NewsWe Hope to Print”

VOL. CLVIV . . No. 54,631 NEW YORK, MONDAY, JULY 4, 2011 FREE

Today, clouds part, more sunshine, recent gloom pass -es. Tonight, strong leftward winds. Tomorrow, a new day. Weather map throughout.

The President has called for swift passage of the Safeguards for a New Economy (S.A.N.E.) bill. The omnibus economic package includes a federal DITA toolbox, mandatory “True Cost Reducti-on,” a phased withdrawal from complex documentation toolsand other measures intended to improve life for ordinary Tech-Writers. (See highlights box on p. A10.) He also repeated earlier calls for passage of the “Ban on Copy-ing” bill currently making its way through Congress.

Treasury Secretary Paul Krug-man stressed the importance of the bill. “Manuals make great ser-vants, terrible leaders, and absurd religions,” said Krugman, quoting Paul Hawken, an advocate of cor-porate responsibility and author of “Cut-Copy-Paste, How the Larg-est Movement in the World Came into Being and Why No One Saw It Coming.”

“At this point, the manual is our

leader and our religion. No won-der the median standard of infor-mation has been declining for so long.”

Krugman said that the new Treasury bill seeks to ensure the usability of all information, rather than simply supporting large cor-porations and wealthy users. “The manual is supposed to serve us. Unfortunately, we have ended up serving the manual. That’s very bad.”

Much as Roosevelt, after the Great Depression, put the brakes on C.E.O. wages and irresponsible banking practices, administration of!cials claim that today we need to rein in the industry that has caused such chaos and misery.

“The building blocks of trueinformation are simple enoughto create, once the technology isin place,” said House Speaker Nancy Pelosi, who initially op

Governments To Adopt DITA

By JUDE SHINBIN

WASHINGTON — Operation User Freedom and Operation En-during Documents were brought an unceremonious close today with a quiet announcement by the Department of Information that all new documents will use DITA.

“This is the best that could havehappened in the development ofusability in user documentation,” DoI spokesman JoAnn Hackos said at a special joint session of Congress. “Today, we can !nally enjoy information whenever we need it, and wherever we can use it in the best possible way.”

As U.S. and European govern- ments are rewriting their texts,the United Nations will move in toperform duties and aid in rebuild- ing legacy knowledge bases. They will be responsible for keeping the knowledge available; coordinating

Continued on Page A10

DITA 2.0 OUT NOWIndustry Sets Its Sights OnReusable DocumentationTrue Cost Reduction, Increased Trust In DITA

By T. VEBLEN

Special Edition

If DITA users start using less “geekspeak” and learn how to sell DITA to their managers, their world might become a better place to work in.

jang@jang.nl

JANG Communication

Jang F.M. Graat is a very experienced presenter and trainer and loves to travel. If you are interested in his presentations or consults, check out his website and/or send an e-mail.

www.jang.nl