Skip to main content
DITA

The hidden costs of DITA

Originally published in STC Intercom, April 2008

DITA is a free, pre-made XML document structure. That statement can lead to a few erroneous assumptions: if it’s free, then it will cut down on costs, and if it’s pre-made, it will cut down on labor. There are several things to consider when choosing a DITA solution. Does your staff have the skills to author in a DITA environment? Will additional training be required? Does DITA even match your content model, and if it doesn’t, is it worth the effort to change?

Sarah’s conclusion? “DITA may be free, but it’s not cheap.”

Download the PDF (950 K)

Read More
Conferences

WritersUA: DITA pilot techniques

Mark Wallis of IBM ISS on how to run a successful DITA pilot. Some great information in this presentation on how to reduce risks.

He recommends selecting your pilot project based on the following items:

  • Right timeframe — don’t choose the project that has an imminent release
  • Choose a manageable documentation set size
  • Reduce risk by avoiding the strongest (or most critical) product
  • Identify a product with a known need to improve the user experience

They had one person out of a group of twelve, a “senior in name only” writer, leave because of this transition.

The ideal team for a pilot will need cross-functional and complementary skills:

  • Project management skills
  • Tools and technology strengths
  • Product knowledge and understanding
  • Architecture and design skills
  • Editor for standards and styles

Some advice on planning your content. (And it’s worth noting here that these apply to good writing and topic-oriented content rather than to DITA tools.)

  • No autopilot writing
  • Don’t just migrate existing content; you’ll get trapped in old paradigms (this assumes that existing content does not fit the DITA topic paradigm)
  • Perform use case analysis and task analysis
  • Determine the critical scenarios to document
  • Focus on tasks; backfill supporting information as needed

Some interesting discussion of “task support clusters,” which include conceptual overviews, related tasks, deep concept, and reference information. (Michael Hughes did a presentation on this earlier today, which I unfortunately was not able to attend.)

They set up a DITA War Room in a small conference room and met at least daily (1.5 to 2 hours per day. Yikes). They set weekly goals and used small tasks to build momentum.

There was also heavy use of an internal wiki to put up initial “straw man” design, then revise, comment, and discuss.

Layering deliverables
Implementation deliverables were split out into smaller tasks, such as:

  • Creating topic files, links, and navigation
  • Testing links from code and navigation
  • Creating task and reference topics
  • Validating help against the user interface
  • Creating concept topics for principles, guidelines, and best practices (“deep concept”)
  • Validating content in the expert community

For the third time, he points out that they are no longer documenting how to use a check box, so I guess I’ll mention it.

Choosing the DITA toolset

Task Modeler (free) for building and managing ditamaps, defining relationships between topics, and creating skeleton topics (stub files).

DITA-compliant editor to edit your topics.

Compiler (part of open source toolkit). Compiler? What are they compiling? HTML Help? Oh. He just referred to Ant as a compiler. Ohhhhhkay.

Proof of concept

They picked a subset of the pilot to do the proof of concept.

The presenter’s boss is quoted as saying, “There’s no such thing as bad weather, only insufficient clothing.” I’m guessing that she’s never been to Minnesota in winter.

The objectives for the proof of concept:

  • Learn and evaluate tools
  • Address technical obstacles
  • Specify end-to-end requirements

They learned that deliverable formats matter because they must deliver several different formats.

Managing costs

Purchase toolsets only for pilot team.

After completing proof of concept (successfully!), invest in tools for the remaining writers.

Wiki

They used their wiki to capture conventions and guidelines.

Improving acceptance

They paid attention to the change management issues. He doesn’t mention it here, but I would assume that the combination of an acquisition by IBM plus the requirement to change the authoring environment could have caused significant angst. Their approach included presentations, wiki content, email discussions, and online training.

At the point of transition, DITA boot camp was offered.

They used collaborative walkthroughs, or reviews, to help standardize their content development. Interesting. This sounds as though it could be a) threatening and b) an unbelievable time sink. But just maybe it might also c) help improve the content.

Other lessons learned

Think more, write less. (Don’t document the obvious, don’t document common user interface convention, write only if you’re really adding value.)

Don’t squander your ignorance. (If something makes you stumble in the interface, that will probably also cause problems for your users, so capture it.)

The more structured your content, the easier the transition to DITA.

Documenting the obvious teaches readers to ignore your text, so don’t document the obvious.

The handouts are available here: http://www.writersua.com/ohc/suppmatl/

Read More
Opinion

Content creation isn’t just for tech writers

We’ve seen an increase in the number of clients who need documentation processes that include input from part-time contributors (particularly engineers). XML-based workflows make it easier to handle this sort of input. Part-time contributors can enter their information into forms or can edit XML documents in an editor that doesn’t require them to know a thing about publishing tools.

UC Irvine seems to have picked up on this trend in collaboration: the school’s extension program just announced a technical writing class for engineers:

This course is designed to provide students with writing skills tailored for the science and engineering fields and to correct common problems, said Jessica Scully, M.J., instructor of the course. It covers the importance of writing for a particular audience, and applies journalism skills to help students effectively create a focused and concise document.

The benefits of such a program go beyond engineering. Improvement in the quality of developers’ writing would likely mean a reduction in the cost of creating a more unified voice in content (which in turn would lead to a smoother localization process). And last but not least, the end users (internal or external) would get better documentation.

This class could also help engineers gain an appreciation of the skill sets technical writers bring to an organization. That being said, it would be unfortunate if a company made the short-sighted mistake of thinking that sending engineers to a class like this would transform them into instant technical communicators.

Read More
XML

When is XML the wrong answer?

Originally published in STC Intercom, November 2007

XML can benefit a publishing workflow in many ways: improving content reuse, consistency, and potentially automating much of the process. That all sounds wonderful, but XML is not the logical answer for everyone.

Implementing a structured authoring solution requires a significant change from the familiar desktop publishing routine to new tools, technologies, and processes. Switching to XML is going to cost time and money. Depending on your needs, it may not be the most efficient solution.

Download the PDF PDF file (350 K)

Read More
Conferences

tekom: Benefits for North American writers

My post about tekom generated some interesting comments, including this one, which I will address in pieces:

Thanks for this info. I’ve been lobbying my company to send me to Tekom for the last few years, unsuccessfully. I submitted 2 times for presentations but both were rejected. Our company is in Concord, Massachusetts, USA.
Could you discuss the benefits to North American writers attending such an international event. Are there things you learned there you will not learn anywhere else (business/tech stuff of course )

Interesting question.

Read More
Opinion

The Age of … Expertise?

Over on O’Reilly’s Radar blog, Andy Oram has a fascinating article about the demise (!) of the Information Age and what will be next:

[T]he Information Age was surprisingly short. In an age of Wikipedia, powerful search engines, and forums loaded with insights from volunteers, information is truly becoming free (economically), and thus worth even less than agriculture or manufacturing. So what has replaced information as the source of value?The answer is expertise. Because most activities offering a good return on investment require some rule-breaking–some challenge to assumptions, some paradigm shift–everyone looks for experts who can manipulate current practice nimbly and see beyond current practice. We are all seeking guides and mentors.

What comes after the information age? (be sure to read the comments, too)

It’s an interesting idea, but I don’t think we’re getting away from the Information Age into the Expertise Age. After all, expertise is just a specialized (useful!) form of information.

In the comments, Tim O’Reilly points out that the real change is in how information is gathered and distributed with “the rise of new forms of computer mediated aggregators and new forms of collective curation and communication.”

I believe that we are still firmly in the Information Age because information has not yet become a commodity product. There is, however, clearly a shift happening in how information is created and delivered. I think it’s helpful to look at communication dimensions:

  • Traditional technical writing is one-to-many. One person/team writes, many people consume it.
  • Wikis are many-to-many. Many people write; many people use the information.
  • Mailing lists are many-to-one. Many people respond to one persons’ question.
  • Technical support is one-to-one. One person calls; one person responds.

Technical support is the most expensive option; it’s also often the most relevant. Technical writing is more efficient (because the answer to the question is provided just once), but also less personal and therefore less relevant.

Many technical writers are concerned about losing control over their content. For an example of the alarmist perspective, read Joanne Hackos’s recent article on wikis. Then, be sure to read Anne Gentle’s eponymous rebuttal on The Content Wrangler.

Keep in mind, though, that you can’t stop people from creating wikis, mailing lists, third-party books, forums, or anything else. You cannot control what people say about your products, and it’s possible that the “unauthorized” information will reach a bigger audience than the Official Documentation(tm). You can attempt to channel these energies into productive information, but our new information age is the Age of Uncontrolled Information.

Furthermore, the fact that people are turning to Google to find information says something deeply unflattering about product documentation, online help, and other user assistance. Why is a Google search more compelling than looking in the help?

Read More
Conferences

TOC: Tim O’Reilly/Publishing 2.0

What do killer Internet applications have in common?

  • Information businesses (publishers??)
  • Software as a service
  • Internet as platform
  • Harnessing collective intelligence

Web 2.0: harness network effects to get better the more people use them.

  • Google: every time someone makes a web link, they contribute
  • eBay: critical mass of buyers and sellers hard for others to enter
  • amazon: 10M user reviews
  • craigslist: self-service classified ads, users do all the work
  • YouTube: viral distribution, user creation, user curation

Each of these companies is building a database whose values grows in proportion to the number of participants — a network-effective-driven data lock-in. (gulp)

Law of conversation of attractive profits

  • When attractive profits disappear at one stage the opportunity will usually emerge at an adjacent stage.
  • PCs used to be expensive. Software became expensive. Free precursor to rediscovery of value in some other form.

And thus, if digital content is becoming cheap, what’s next? What’s adjacent?

For publishers, the question is: where is value migrating to?

Asymmetric competition

  • craigslist has 18 employees, #7 site on the web (2005 numbers)
  • All others in top 10 have thousands of employees.

Curating user-generated content

  • The skill of writing is to create a context in which other people can think. — Edwin Schlossberg
  • The skill of programming is to create a context in which other people can share.

Collaborative authoring

What job does a book do? What is a book’s competition?

  • Harry Potter’s competitor is World of Warcraft
  • Encyclopedia Britannica — Wikipedia — Google
  • Books compete with information available online
  • Teaching/reference/edutainment

Search is most important benefit of content being online

“Piracy is progressive taxation”

  • Benefits the books at the bottom that would be lost
  • How to balance/manage a progressive taxation system
  • Gain more sales on the bottom end

DRM: “Like taking cat to a vet” (hold them very carefully and loosely!)

More options = happier users

Read More
Conferences

TOC: Chris Anderson/Free: The economics of giving stuff away

Chris Anderson, editor-in-chief, Wired Magazine

The cost of things tend to fall to zero over time.

You can build business around giving things away:

  • Free samples
  • Skype, YouTube, free unlimited storage on Yahoo
  • Ad-supported media..product is free, make it back on ads
  • Free ice cream samples
  • Give away razor, sell blades
  • Gift economy/wikipedia, craigslist: people donate expertise/time for nonmonetary — attention, reputation, expression…never before “dignified” as an economy. There is an economy, just money is not the currency.

If marginal cost of reaching the N+1 customer is approaching zero, then treat the product as free and figure out how to sell something else.

The price of a magazine like Wired is arbirary; it bears no relationship to the actual cost of the magazine. The subscription price is intended to qualify your interest. Setting the price too low “devalues the product.”

Most music is free. “Free as in speech” — DRM is going away. “Free as in beer” — bands are experimenting with giving away music to market the live performances.

Games and movies would be free if not protected. They are locked down to enforce prices. Artificial barriers tend to fall over time. Already seeing ad-supported videogames. (neopets)

The shining exception: Books! They are not asymptotically approaching free. Books make sense. They provide the optimal way to read. The physical product is better than digital product…excellent battery life, screen resolution, portable, and it even looks good on your shelf. Easy to flip through.

If “free” is “the business model of the 21st century,” how could a book be free?

(This was preceded with a disclaimer that many of these options would be “offensive” to people in the audience.)

For his next book, Anderson wants to do the following:

  • Audiobook will be free with book (mp3) (free coupon in real book)
  • Will participate in book search, include Google
  • Considering an e-book locked to a specific reader for free
  • Unlocked e-book with advertising inserted
  • Book online with ads in the margins
  • As many sample chapters as publisher will accept

How could a physical book be free?

  • Sponsored book
  • Consultants give away books
  • Book with ads
  • Free rebate
  • Free to influentials/reviewers
  • Libraries have always had free books

Why do it?

  • Free book is marketing for the non-free thing
  • Book is marketing vehicle for celebrity
  • Can’t give away time
  • If free version is inferior, you give it away to market the better product
  • Use “free” to maximize reach to new influentials

Why aren’t more people doing free content?

  • Most people are not represented by a speaker’s bureau and can’t monetize fame
  • Online sample is not a compelling example of book (maybe for cookbook, probably not for novel)
  • No natural advertiser
  • Publisher opposition — publishers not in business of selling celebrity
  • Annoys the retailers
  • Fear and timidity/fear of cannibalization

The most critical point: The interests of the author and the publisher are critically misaligned. Publishers doesn’t benefit from speaking fees of consulting fees, only from book sales.

Sounds like an argument for self-publishing to me.

Read More
Conferences

Tools of Change for Publishing/Norwegian Monks!

As part of a brief history of publishing in the opening keynote, I’ve already seen a few friends:

  • The Norwegian Monks video — Technical support for books
  • A reference to Vannevar Bush’s “As We Might Think” article from 1945

According to Tim O’Reilly, Microsoft Encarta “fatally wounded” the Encyclopedia Britannia because of “asymmetric competition.”

A series of short, related keynotes to kick off the conference. I like this approach; in a nontechnical, high-level keynote, it can be difficult to fill a 60- or 90-minute slot.

Brian Murray, HarperCollins, Retooling HarperCollins for the Future
Consumer publishing *was* straightforward. All promotion wasdesigned to drive traffic to a retailer.

In 2005, “the earth moved.” There were search wars, community sites, user-generated content, Web 2.0. Newspapers and magazines responded with premium, branded sites online based on advertising or subscription models.

Book publishers are confused. Search engines treat digitized book content like “free” content. Rights and permissions are unclear. Books are not online — except illegally! Book archives are not digitized.

Before 2004, “book search” took place in a book store.

What is the role of the publisher in a digital world?
What is the right digital strategy?
What are the right capabilities?
“Search” provides new opportunities for publishers.
Publishers must transition from paper to digital.
How can publishers create value and not destroy it?

Some statistics:

  • 65M in the U.S. read more than 6 books a year.
  • 10M read more than 50 books a year. [ed.: waves]
  • Younger consumers read less; they spend more time online

Search is used more often than email.

HarperCollins decided to focus on connecting with customers, rather than e-commerce. Amazon and others already do e-commerce. They focused on the idea of a “digital warehouse” that is analogous to the existing physical warehouse. They want to:

  • promote and market to the digital consumer.
  • use digitized books to create a new publishing/distribution chain
  • protect author’s copyright
  • “replicate in digital world what we do in physical world”
  • got publicity, strong public response
  • no single vendor who could deliver turnkey

Improvements from digital production and workflow could fund some or all of the digital warehouse investment. Projects that were low priority “IT and production” projects become high priority. Savings were realized in typesetting/design costs, digital workflow, and digital asset management.

The digital warehouse now has 12,000 titles. (Looks as though they were scanned, which doesn’t meet *my* definition of “digital content.”)

At this point in the presentation, we began to hear a lot about “control.” Control of content, controlling distribution, and so on.

HarperCollins does not want others to replicate their 9-billion page archive in multiple locations. They want others to link into their digital warehouse. But if storage is cheap and getting cheaper, what’s in it for, say, Google?

Strategic issues for book publishers

  • Should publishers digitize, organize, and own the exclusive digital copy of their book content?
  • Should publisher control the consumer experience on the web?
  • If the cost of 1 and 2 is zero, should every publisher do them both? would they?
  • How to make money

The focus on controlling content was interesting and perhaps not unexpected. The business case based on savings in digital production was also interesting.

Read More
Opinion

Why XML and structured authoring is a tough transition

Found on technicalwriter’s blog:

There are several applications that incorporate features for DITA use, such as XMetal and Altova Authentic, but how much value do they provide? (Looking over the online documentation for XMetal, you will see some pretty shaky formatting and copyfitting.)

There may well be formatting and copyfitting issues. Wouldn’t surprise me at all. But talk about missing the forest for the trees!

DITA/XML/structured authoring are important because they improve how information is stored. To question their value because somebody produced documentation using them that doesn’t look so great…let’s try an analogy:

Last week, I went to a restaurant and the food was terrible. I looked in the kitchen and saw Calphalon pots and pans. I conclude that you should not buy Calphalon because the food they produce is terrible.

The quality of your food is determined by things such as the quality of the ingredients and the skill of the chef. The pan you choose does contribute — it helps to use the right size and a high-quality pan, but to dismiss DITA because one example doesn’t look quite right is pretty much like dismissing Calphalon because somebody once cooked something that didn’t taste very good in it.

PS I like Calphalon. And I have produced my share of problematic entrees.
PPS DITA is not right for everybody.

Read More