This presentation was delivered at DITA Europe 2009 in Munich. It is about trying to sell technology to an audience who might not be interested in technology for technology's sake.
It was the most fun presentation I ever gave. People in the next room were wondering what all the applauding and laughter was about.
Developer Data Modeling Mistakes: From Postgres to NoSQL
Geeks don’t sell DITA: Understanding different perspectives
1. Geeks don’t sell DITA
JANG F.M. Graat
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.
2. Hello,
I’m Hans
Meet our hero. He is a technical writer at a medium-sized company and takes his profession
seriously.
3. 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.
4. 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...
5. 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.
6. The Darwin Information Typing Architecture
(DITA) is an XML-based method for writing
Gee
and delivering information in a variety of
kSp
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
eak
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
Hans has no doubttags. For understand the benefits of this great new technology. He
to getting intothat hisgives his boss the short techie<p> denotes [...]
HTML it and boss will example, introduction to DITA.
is really
7. DITA ? transformation ?
conref ?
XML ?
tags ?
XSLT ?
processor ?
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.
8. <task id="washcar" xml:lang="en-us">
<title>Washing the car</title>
<taskbody>
<steps>
Sil
<step>
Gee ly
<cmd>Move the car onto the
kSp
driveway.</cmd>
</step>
<step> eak
<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>
So Hans comes up with one of the standard examples from the DITA toolkit: procedures for
</step>
washing the car. Unfortunately, this does not really help him convince his boss...
9. NOT
WO
RK
First 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.
10. 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.
11. 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.
12. 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 !
13. 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.
14. 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.
15. 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.
16. no DITA
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.
17. DITA ? saving resources
cutting costs
ROI
free extras
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.
18. First, we need to create a DTD and buy an
Gee
XML editor. Then we define a specialisation
for our company and the translation rules
from the standard DITA DTD to ours. Also, we
kSp
create read-write rules and an XLST file to
translate the sources to various outputs.
After the topics are defined we create one
eak
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.
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.
19. 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”.
20. 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 ?
21. 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.
22. 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 ?
23. 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.
24. 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.
25. 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.
26. 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.
27. 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.
28. 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 ?
29. 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.
30. DITA ? higher quality
modular design
reuse
ROI
various outputs
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.
31. 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.
32. The Future of DITA ?
Special Edition
Today, clouds part, more
“All the News sunshine, recent gloom pass -
We Hope to Print” es. Tonight, strong leftward
winds. Tomorrow, a new day.
Weather map throughout.
VOL. CLVIV . . No. 54,631 NEW YORK, MONDAY, JULY 4, 2011 FREE
DITA 2.0 OUT NOW
Industry Sets Its Sights On
Reusable Documentation
True Cost Reduction, Increased Trust In DITA
By T. VEBLEN Governments To
The President has called for
swift passage of the Safeguards
leader and our religion. No won-
der the median standard of infor-
Adopt DITA
for a New Economy (S.A.N.E.) bill. mation has been declining for so By JUDE SHINBIN
The omnibus economic package long.”
includes a federal DITA toolbox, Krugman said that the new WASHINGTON — Operation
mandatory “True Cost Reducti- Treasury bill seeks to ensure the User Freedom and Operation En-
on,” a phased withdrawal from usability of all information, rather during Documents were brought
complex documentation tools than simply supporting large cor- an unceremonious close today
and other measures intended to porations and wealthy users. “The with a quiet announcement by the
improve life for ordinary Tech- manual is supposed to serve us. Department of Information that all
Writers. (See highlights box on p. Unfortunately, we have ended up new documents will use DITA.
A10.) He also repeated earlier calls serving the manual. That’s very “This is the best that could have
for passage of the “Ban on Copy- bad.” happened in the development of
ing” bill currently making its way Much as Roosevelt, after the usability in user documentation,”
through Congress. Great Depression, put the brakes DoI spokesman JoAnn Hackos
Treasury Secretary Paul Krug- on C.E.O. wages and irresponsible said at a special joint session of
man stressed the importance of banking practices, administration Congress. “Today, we can finally
the bill. “Manuals make great ser- officials claim that today we need enjoy information whenever we
vants, terrible leaders, and absurd to rein in the industry that has need it, and wherever we can use
religions,” said Krugman, quoting caused such chaos and misery. it in the best possible way.”
Paul Hawken, an advocate of cor- “The building blocks of true As U.S. and European govern-
porate responsibility and author information are simple enough ments are rewriting their texts,
of “Cut-Copy-Paste, How the Larg- to create, once the technology is the United Nations will move in to
est Movement in the World Came in place,” said House Speaker perform duties and aid in rebuild-
into Being and Why No One Saw It Nancy Pelosi, who initially op
ing legacy knowledge bases. They
Coming.”
will be responsible for keeping the
“At this point, the manual is our Continued on Page A10
knowledge available; coordinating
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.
33. JANG Communication
www.jang.nl jang@jang.nl
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.