by Sheila Loring

Michael Boses, CTO
Invision Research (www.invisionresearch.com)

Yes, Virginia, you can author XML in Word.

Company founded in 1996. Xpress Author for Word launched in 2002. Early markets were defense intelligence, central government, and pharmaceutical industry.

Focused on enabling Web 2.0 technologies with structured authoring.

In.vision provides structured authoring interface inside Word. Toolbars configured for XML are displayed. Menus are also tailored for XML authoring. Based on the cursor location in the document, only valid items show up in the menu. So you can’t insert a figure where only a title is valid.

Authoring based on styles. The styles drop-down list shows valid elements based on where you’ve clicked in the document.

Templates available. For example, create a document using the text book template, [Type title here] is displayed where you’ll type the chapter title, placeholders for objectives, review questions, further reading are also displayed. Boilerplate text can also be saved in the template.

You can copy and paste content (including graphics) from other types of documents — standard Word documents, spreadsheet, browser. Even a table with merged cells can be copied and pasted into structured doc. Structure is automatically applied.

Word’s beloved revision tracking and commenting features are supported. This information is stored as metadata in the document, and you can specify the type of comment based on your defined structured (such as a legal or draft comment).

Spell checking and thesaurus are also supported.

You can display a document map, which shows headings in the document. Click on headings to navigate through document.

What happens when you paste content into an invalid location? When you right click to paste the content in an invalid location, the drop-down menu Paste item is grayed out. If you Ctrl-V to paste, the cursor flashes to indicate illegal action (too subtle an indication for my tastes), or you can configure the program to display a friendly dialog box.

How do you see the XML tags? I found Michael’s response entertaining: We have a promise to the users never to show the tags. Not the answer I had hoped for!!!!! You can, however, export the document to XML and then display and/or edit the file in an XML authoring tool (Oxygen and XmetaL are my personal favorites, BTW).

Unfortunately the demo ran short, so we didn’t get to see much else, which is unfortunate. The web site (http://www.invisionresearch.com/xpress.html) doesn’t offer much detailed information, but do check out the brochure: http://www.invisionresearch.com/pdfs/xpressauthor.pdf. I have to chuckle at the front page of the brochure. Envision a suited gentleman with white hair and furrowed brow. “If you’re frustrated with XML authoring, we have a Word for you.” The photo says it all.

Based on what I saw, Xpress Author might be a good alternative for technically challenged content providers or companies married to Word. It isn’t, and doesn’t pretend to be, a heavy-duty XML authoring tool.

by Sheila Loring

Nicoletta Bleiel
Senior Information Developer
ComponentOne

Quick summary: Web 2.0 technology can enhance technical documentation, but the disorganization and narrow focus make it a poor replacement for sound technical documentation.

Wikis, podcasts, community forums, widgets/gadgets, blog, and social network sites such as Facebook and MySpace are all examples of Web 2.0. Unless you’ve been living under a rock for the past 5 years, you already know this!

The bottom line is always giving your customer what they need. Nicky provided a refresher course in product and user analysis: scheduling site visits to watch the customer use your product, reading the customer forum on your company’s web site, asking tech support for common customer problems, and so on.

Find out how users interact with your product. Do they have the time or inclination to flip through a book, or do they prefer short training videos or cheat sheets? Are they comfortable navigating online forums to find help, or do they prefer online help? Do they have an Internet connection to access online forums or content? Customers with lots of feedback are more apt to participate in forums or blogs, particularly those who are passionate about the product.

Advantages of wikis: users contribute at their convenience, way to build communities of practice (COP), keeper of group memory.
Disadvantages: wiki syntax not intuitive, can be difficult to learn, malicious comments require censorship or some response, often unstructured and disorganized.
Check out this wiki: http://wikihow.com (collaborative attempt to build the world’s largest, highest quality how-to manual, everything from surviving a riot (http://www.wikihow.com/Survive-a-Riot) to crocheting a cat hat (http://www.wikihow.com/Crochet-a-Cat-Hat).

Advantages of podcasts: informal, very useful for certain audiences, easy to create, free or inexpensive, easy to find on iTunes, keywords in podcast increase findability.
Disadvantages: might not work for your customer (computer with no soundcard), need to generate material frequently.
Notable podcasts/podcast tools: talkshoe.com (live shows on web kind of like Webex, recorded as podcast), audacity.com (free podcast recording software), Odiogo at http://www.odiogo.com (text-to-speech converter)

Advantages of blogs: can optimize search engine results, used to promote/educate customers about product features, casual way to communicate with users.
Disadvantages: require frequent contributions or lose audience, must respond to feedback.

In summary:
Always maintain solid user assistance as a foundation.
Web 2.0 enhances but doesn’t replace what we do.

See the slides at http://www.doctrain.com/west/program_detail/documentation_planning_and_library_design_in_a_web_20_world/.

by David Kelly

This session was presented by Raymond Yang Lei, a senior information architect with Huawei (a large telecommunications company in China). Mr. Lei apologized for his English, this being his first opportunity to use it in a public forum. And, in truth, there were some details that probably got lost in translation, although JoAnn Hackos was present to help clarify points of confusion.

(I believe most of the bilingual Chinese people in the Bay Area at that time were gathered in downtown San Francisco, engaged in other business.)

Mr. Lei’s story of a DITA migration was similar in many respects to the other stories we heard during this conference. Drivers for the migration included rapid growth of products, versions, and customers, and requirements from their customers for world-class documentation quality. (I formerly worked for a company that was occasionally in direct competition with Huawei. Telecommunications is heavily regulated, and while the actual writing quality may not be at issue, the format, timeliness, and accessibility of technical data can be a deal breaker.)

Reasons for choosing DITA were similar to others mentioned in previous posts. One interesting comment he made: one reason for choosing DITA was the growing user community. I heard, informally, from other people that they were initially skeptical of DITA simply because it was open source, open standard, and those kinds of projects were typically ephemeral. I believe there is a growing sense that DITA is likely to have greater longevity and penetration than was initially suspected.

Okay, I need to get to the airport soon so I’m going to wrap this up quickly – will try to repost if more occurs to me during the long flight. So here are some quick points:

* They used an Excel spreadsheet to identify subject/topic completeness and organization. Later this spreadsheet outline was used, via an external application they developed, to generate a ditamap and create links to the appropriate topics. Very cool.
* They use Clearcase to store and version content. It’s not a CMS, I’m here to tell you.
* Changing roles include the fact that the Information Architect and writers must now be more aware of a broader scope of product knowledge in order to structure data and reuse data appropriately.
* They evaluated all the CMSes they could and rejected them all. Reasons: Unicode support does not mean Chinese-ready; not all the CMSes fully supported DITA; CMSes are expensive, particularly in China, and the ROI does not justify it.
* Their localization consists of writing in Chinese and translating almost simultaneously to English, then publishing both simultaneously. Eventually they plan to write primarily in English.

There were a couple of other interesting points — but I’m out of here. Cheers!

by David Kelly

This session was presented by Padma Nappalli from Intel Corporation and described her documentation department’s experience migrating from a standard Frame/HTML environment to a DITA/CMS environment.

Many of the situations, frustrations, and successes that their team encountered sounded similar to those of other migration stories I heard at this conference (and that I have also experienced). Publishing requirements multiply, customizations are needed in output, multiple legacy formats are difficult to maintain, quality and timetables suffer, customers complain.

Ms. Nappalli’s department began researching XML solutions in 2005 and are now in production using DITA and Documentum. Documentum was already in-house, and they had little to no budget, so that’s what they use.

They discovered that with DITA they did not need a CMS right away. It was more important to structure the source material. They now have 6000+ topics in DITA, and they are able to supply man pages from DITA as well as PDFs, CHM, and HTML output. She said they had to develop their own method of outputting man pages from DITA as they could not find any solutions available.

Like others, they have seen a shift in roles, not only individually but departmentally. Two examples: one person was hired “as a writer,” knowing that he would become their publishing tools person. And they now have a CMS admin, so the department has taken on an embedded IT function.

A few unique points from her presentation:

* They still need to use Robohelp and FAR (not sure what this is) for helps, but it is last-minute production that takes far less time than before.

* They trained a single writer to rework the legacy data and do the conversion, to reduce overhead. Here is where the comment came out that she believed it was beneficial to do source tweaking before conversion.

* She says “It is not possible to use DITA out of the box.” So plan on tools development.

* They had the “blessings” of management, but no funding, no IT, and no tools development support. In spite of this, they apparently managed to obtain all of these things eventually, one way or another. To this point she told the traditional story of “The Arab and the Camel.” Although I’d heard it many years ago, I’d forgotten it, so I’ll repeat it here:

Out in the desert there was an Arab with a tent, and his camel waiting outside. A tremendous rain started coming down. The camel came over to the tent and asked if it could just poke its head inside to keep it dry. The Arab agreed, yes, that would not take up much room. Then the camel asked if it could bring its neck in, and the Arab agreed. Next came the shoulders, then the trunk and legs, then the tail, and soon the Arab found himself sitting in the rain.

I believe that is called an incrementalist strategy. Apparently it also works outside of folk tales.

Cautions that Ms. Neppalli passed along:

* Do thorough content analysis (I’m sensing a theme here)

* Think big, start small

* Don’t rush to conversion

* Start with highly structured content

* Don’t rush to buy tools (although she says the tools are much better now than when they started). She said their biggest challenges was in the tools.

* “Sandbag Your Plans.” Expect the unexpected. There will be surprises.

As I sit here typing in my hotel room, one of the 150,000 or so people bumped from an American Airlines flight, I wholeheartedly agree.

by David Kelly

This session was presented by Bruce Nevin, Program Manager and Information Architect for Cisco. His purpose was to present some of the drivers for moving to DITA. The raw data for the presentation came from Cisco’s own migration to DITA, which he called “an adventure.”

Initially they had developed their own information model after having evaluated and rejected DITA while it was still in its early stages. At a certain point the proprietary model became problematic, so they re-evaluated DITA. He stressed that the reasons for choosing DITA in the second round were more business reasons than technical. In a comparison of the technical aspects of DITA and the proprietary data model, the main differentiator was specialization, which, while valuable, was not a compelling reason in and of itself.

As an Information Architect and an academic linguist, Mr. Nevin strongly recommended performing a content analysis to specify the structure of you content. This leads to “discovery” – identification of inconsistencies – and “opportunities” – to make structures consistent. I would think one could also identify latent structures and find ways to make them explicit during this phase.

Some of the criteria that led them to select DITA included:

* Ease of sharing of data with their corporate acquisitions

* Long-term supportability (apparently a big issue with the proprietary data model – the IT department had problems with it)

* Vendors charge less for translating DITA (this, he admitted, was a rumor he had heard)

* Tool vendors can preconfigure for DITA.

Some challenges for DITA:

* It’s immature

* Industry standard specializations are needed

* It is based on XHTML format tags (for instance, he believes that a table and a list are the same thing and that the distinction is unnecessary legacy baggage)

* Filled with IBM legacy information (see audience comment in the session on the troubleshooting specialization)

* It is limited to DTD spec, even in the schema (not sure I understood this point)

The costs of going to DITA could be managed by a few helpful practices he mentioned:

* Cost: rewriting XSL. So delay specializations as long as possible.

* Cost: conversion. So use a quick and dirty, vanilla conversion as long as it renders okay.

* Cost: rendering. Leverage the Open Toolkit code as far as possible. But it will still require a lot of work. (I am prepared to sign an affidavit to support this statement.)

* Cost: customizations. So leverage vendors’ code, integrate with Open Toolkit. One example was Cisco’s command syntax for its network OS. They have a tool they built to integrate with XMetal that provides a pop-up from which you select human-readable elements of the syntax, and it populates the DITA file with the correct tags.

Of these, he considered specialization and XML cleanup deferrable processes in the migration process, but rendering and customization to be nondeferrable.

Management issues they encountered:

* Disparate priorities among the groups (limit size and complexity, get easy wins, try to maximize ROI as early as possible)

* Minimizing disruption to production (start with easy projects, avoid having writers switch between legacy work and DITA work, avoid round-tripping content – migrate only one direction)

It took Cisco 2-1/2 to 3 years for their migration effort.

A discussion arose based on an audience question. What factors would drive the migration timeline? Bruce thought it was a good question, he just had not thought it through yet. Some answers from both him and the audience:

* Money

* Time commitment

* Taking time to do research and make good decisions.

* Content analysis (familiar chorus). “Language is structured, XML makes it explicit.”

* Starting with well-structured writing “gets you 70% there” (Information Mapping mentioned)

* The need to migrate from disparate tools/processes

* Conversion while producing. Recommended incremental rollouts rather than mass conversion of all documents.

* Size of company is a variable.

* Avoid the pilot project also being a production project – “You don’t know what will happen.” But some audience members said they did not want to waste effort, so they picked projects that were only loosely time constrained or that were small enough to permit parallel development. One person said they also went for a project that had enough wow factor to get management’s attention.

by David Kelly

This session was presented by Scott Wolff of WOLFF & Associates, LLC. From my perspective, other than the sessions that presented testimonials of successful DITA/CMS conversions, this was one of the more on-target sessions I heard.

The substance of this presentation was to identify several DITA-relevant CMS functions, then show how a given CMS handled that function successfully. The intent was not to compare all CMSes per relevant function, but to provide some tools for undertaking that kind of evaluation oneself. And, of course, when asked whether he had come to any conclusions, Mr. Wolff replied, “Yes, and I’m available to be hired for consultation.” Or you can start with his suggestions and do the work yourself.

Again, I won’t rehash everything he said, but will focus on some interesting points:

* Eight vendors provided screen shots for his talk.

* CMSes can run anywhere from 10K (“But you won’t like it”) to $1M – $7M. All of the CMSes he presented could be had for less than $200K.

* DITA does not require a CMS because relationships between elements are tracked internally (links, conrefs, topicrefs). But CMSes provide other, “extra-DITA” values to content, including version control, where-used functions, workflow management, security, and asset protection (backups).

CMS functions he thought important, and the systems that did them well:

* Drag’n'drop ditamap editor (Vasont)

* In-system editing of DITA attributes (Vasont)

* Import new DTD to reconfigure the data model (and update the catalog) (Trisoft)

* Support for conrefs (usually difficult because CMSes typically do this) (Trisoft)

* Allow choice of a particular version of a topic for a map to point to (Trisoft)

* Import ditamaps and bring in the target topics, maintaining the links inside the CMS (Empolis)

* Where-used (where is a topic used) function (Empolis)

* What-uses (what uses this topic) function (Empolis)

* IT-friendliness (DITA Exchange, an extension of Sharepoint that gives it DITA capability)

* Word-like editor (DITA Exchange)

* Publish to Word 2007 (DITA Exchange)

* Dynamic folder structure (DITA Exchange – you’ll have to talk to Scott to see what he means by this one)

* Edit relationship tables (Ixiasoft DITA CMS Framework)

* Define conref by beginning with target, then finding insertion points (Ixiasoft)

* Integration with editor (Ixiasoft/XMetal)

* Diffing on ditamaps (Ixiasoft)

* Lease time on server rather than buy CMS (Astoria)

* Return search results as a ditamap (Astoria)

* Conditional publishing, filtering based on production status at the last minute (Astoria)

* Conditional publishing a different way (XyEnterprises Contenta)

* Maps and ditavals dynamically created (not sure how this works…) (XyEnterprises)

* Creation of an object that associates document resources into an object for document creation (Inmedius Horizon) (Does that sound like the definition of a ditamap? I’m curious how they are different.)

I should note that these functions and the systems are not a comprehensive list of what should be evaluated in a CMS. Several people, including Scott, mentioned JoAnn Hackos’ book on CMSes as being very helpful.

Also, I believe Scott would agree that his mention of one system for any given function did not mean that other systems would not also have good (or acceptable) solutions for the same problem.

Some warning signs that Scott proposes when evaluating CMSes:

* Solutions not seamless with DITA – “DITA-compatible” because they export DITA does not mean they store DITA XML – this can lead to configuration issues when changing data structures.

* CMS does not track DITA components – therefore it can’t track relationships between components.

He suggests that with a CMS will come new roles. This was echoed in several other presentations – new technologies mean new roles for writers and editors.

Maybe even managers? Can managers be retrained? Do I smell a possibility for a new presentation?

Finally, in response to a question as to whether there was an open source CMS that tracked DITA components, one of the audience members brought up “Componize,” a CMS based on Alfresco (another open source CMS) that would provide DITA component-level management. It is apparently available on Sourceforge. I have no other information to vouch for its appropriateness as a DITA/CMS solution. So go have fun – just don’t blame me!

by David Kelly

This session was presented by Joe Gollner, VP of e-Publishing Solutions for Stilo International.

When I first saw a “Stilo” case being carried in for their booth, I thought they might be associated with the Stilo Fountain Pen store I had seen just the day before in San Francisco. As someone who works for Scriptorium and who writes for a blog called “Palimpsest” I should have known better. Stilo does document conversions, among other things.

Slight diversion here. When I ran into my networking glitch early in the conference, I left my laptop in the hotel room and decided to just make notes in my conference proceedings book. I used a Cross ATX fountain pen, which I had to refill quite often. Then I took the proceedings back to the room, where I transcribed, distilled, commented, edited, rewrote, posted, and reposted to my little heart’s content. The irony of using what Mr. Gollner would call an “opaque” documentation method while sitting in a room full of extreme high-tech documentation practitioners – well, I’m not stupid. (Well, maybe I am, but not like that.) But I found the method curiously effective. When I hand-write, I focus on what is being said better, and, whether by muscle memory or (as research suggests) the immediate translation of auditory speech to written word, I retain more of what I hear. And the subsequent transcription process gives me the opportunity to…well, see above. It just took a lot more time than expected. And of course, now you have to endure these lengthy soliloquies.

Okay, back to the conference:

The central point to Mr. Gollner’s presentation was summed up, I think, by his reference to content as an Easter Bunny. You think you have nice content, nice Easter Bunny. Then he showed a slide with a monster bunny and the words “The Easter Bunny Hates You.” The Easter Bunny, it turns out, is full of surprises. (Look up “The Easter Bunny Hates You” on the web.)

This message was consistent with what I heard in several other sessions: data analysis is key to a successful conversion project. Even plain text has structure. A good conversion project should be able to capture as much as possible of the intelligence expressed in the source.

In speaking about the conversion of documents for a large pharmaceutical lookup portal, the qualities that ideally should be captured in the resulting text, according to Mr. Gollner, include:

Precision

Performance

Navigability

Portability

Timeliness

In general, the ideal criteria for documents before being converted to DITA include:

* valid XML

* modularized

* discretely addressable

* uniquely identifiable via metadata

* linked appropriately

* processable with “almost perfect confidence”

And of course, no one’s documentation looks like that before conversion. Instead, he defines a “spectrum” of document accessibility to conversion:

* Opaque (paper, fiche)

* Annoying (proprietary formats like Quark)

* Polluted (old HTML, things filled with deviations and noise)

* Tolerable (a documented format that exposes format and structure in processable form – to which category he grudgingly admits MS Word and Framemaker)

Against this challenge, his company has devised a process flow that they are able to use in almost all cases. Given that the slides were inscrutably dense, I don’t propose to discuss them. Works for them. They do conversions on the order of hundreds of millions of pages, so I won’t argue. And I imagine the results are of very high quality.

One point raised by your humble correspondent had what I would consider an arguable answer. The approach typically taken by Stilo is to automate all the conversion they possibly can, then do tweaking after conversion. I asked whether there was ever a situation where it might be preferable to do data tweaking before conversion. This is a question I have struggled with, without any helpful metrics, in my own conversions of hundreds or thousands of pages. Mr. Gollner’s answer was that it was always preferable to do the tweaking afterwards. Of course, he also later said the folks in his office would write a conversion script for a single page if given the opportunity.

However, interestingly, this morning I heard a session in which Padma Neppalli of Intel stated that she believed it was beneficial for them to do restructuring and tweaking of the documentation prior to it being converted. Again, without metrics, and at the risk of playing “he said, she said, did so, did not” — it does seem to me that there are opportunities for reducing conversion pains by doing some basic grooming of the source before conversion. It’s sort of like running a dust brush over your vinyl discs before converting them to MP3s (ouch, did I just date myself?). Yes, you can do cleanup of pops and scratches in the digital world, and very quickly from what I’ve seen, but if you have a more convenient method in the old “analog” world to give you a cleaner conversion to begin with — why not? It seems risky to lose information just to put it back later, if you can avoid it.

by David Kelly

This session was presented by Harv Greenberg, Principle Technical Project Manager from XyEnterprises. This presentation focused on the used of mechanisms within the CMS (XyEnterprise’s Contenta CMS, specifically) to develop management tools.

I think the purpose here was to show that CMSs contain a lot of information and capabilities that can be built around content as a way to enhance the value that management brings to a documentation project. Some of the possibilities presented were “well-defined project formation” (similar to the methodologies built into the S1000D specification), and the development of tools for “information quality” (term checking, customer feedback, knowledge base integration, workflow metrics).

The session featured a lot of participation by the audience in suggesting types of management capabilities that would be nice to have, and demos by Harv of Contenta’s capabilities along those lines. One interesting request he said they had had was the use of the CMS as an invoicing system. With a little tweaking they were able to capture hours worked for each portion of built-in workflows and create reports capturing the task/resource information.

I’m not sure I learned a lot with this one other than to try to think about other possibilities for the use of CMSes. And that makes sense – with all the information captured in these systems, there should be a lot of possibilities for doing things with documentation that we have not necessarily considered before.

One thing mentioned in one of the other sessions (maybe it was JoAnn’s) was that the accelerated interest in DITA had renewed people’s interest in CMSes. Perhaps with a stronger adoption rate for CMSes, this will lead to more people thinking about how they can get more value out of these (very expensive) resources.

by David Kelly

This session was presented by Ann Adams of Kyocera and Dan Dube of DocZone.com. The gist of the presentation was similar to several others at this conference, with a little different twist in the type of CMS that was selected. The story was similar to the pattern of others: a limited writing staff and diverse legacy sources as over against an exploding complexity of products, audiences, and document services/output types to fulfill.

Ms. Adams pointed to several keys to success and several points where they learned difficult lessons. Some of the things she thought helped:

* Attending a DITA User’s Group early on.

* XML training for authors. (When the XSL section of a video started, she turned it off – no need to confuse people.)

* DITA training

* A workshop on modular writing.

The CMS they chose, DocZone, helped them accelerate the process because it is a hosted solution – they contract for services rather than purchasing the CMS and related tools. DocZone helped them perform the data structure analysis and performed the initial conversion for them.

One point she made: they have continued to tweak the data structure as they have learned more about the structure of their legacy data. This was a common theme in the implementation stories I heard: take time to understand the structure of your data. More on this in another session.

Other contributions to success:

* Weekly meetings with the writers (“code reviews”)

* Weekely meetings with their vendor

* Using CMS workflow for reviews

Issues they encountered:

* Turnover in a smalll doc department causes significant loss of intellectual capital. One writer left, another writer was out six weeks on jury duty.

* The first conversion was easy, but subsequent documents uncovered more structure. They wound up changing their minds about the data structure so often they wound up purchasing the conversion software so they could reconfigure it at will rather than paying the conversion vendor each time they wanted a change.

Some interesting “side-effects”:

* The CMS provided high visibility into authors’ writing habits (e.g., making numerous corrections to a document over time creates a large version trail) Some writers did not like this.

* The ditamaps were good for book-oriented views, but writers wanted submaps showing only the topics they were working on.

* The concept of “done” is having to be redefined. Consequently it is hard to make estimates of when they will be “done.”

Two advantages they have derived from implementing the CMS:

* Expanded capabilities (new delivery outputs and methods)

* The use of “author memory” has enabled them to reuse source language more effectively.

What is “author memory?” I hadn’t heard that term before. Ms. Adams said that it was “like translation memory,” then introduced Dan Dube, who is, I believe, a product manager with DocZone, who picked up from there.

It turned out that “author memory” was essentially the same as translation memory, but in DocZone it is built in to the CMS. So is translation memory, for that matter. Author memory holds the source material, while translation memory holds the translated material. Except, if I recall the statement correctly, in the case of DocZone, the author memory and translation memory are the same.

At any rate, the “author memory” approach helps the author make fuzzy matches to similar language and decide whether it is viable to use existing language. According to Ms. Adams, this has resulted in significantly more reuse of content than they expected.

There was a discussion about the adoption of DocZone’s version of translation memory vs. traditional (e.g., Trados) mechanisms. Mr. Dube said translation vendors were wary, but were also interested because it enabled them to avoid paying Trados licensing fees to SDL, which also does translations in addition to now owning Trados. Interesting.

The CMS/DITA implementation for Kyocera took about 1 year. This sounded significantly less than the figures I heard for “owned systems”. On the other hand, Kyocera is also now locked in to regular payments — so I guess it depends on what you are looking for and what kind of cost model you are willing to swallow. And, I suppose, how customizable you want your system to be.

by David Kelly

This session was presented by Carolyn Inkster (project manager) and Dan Dionne (technical lead) from IBM. They were responsible for the development of the troubleshooting specialization that has been placed in the open-source keeping of OASIS. It is currently available as a separate download for integration with DITA-OT 1.4.

The need arose based on the variety of problem/resolution formats across IBM’s documentation set. More than once I heard that at one time IBM was the second largest publisher in the world, right after the US Government Publishing Office (or whatever it’s called). They did a business case and determined that clear, consistent formatting would save writers’ time and customer support time sufficiently to make the development costs worthwhile.

Development consisted of two months of part-time haggling over the architecture among the IBM team, and a few days of development for the DTD/mod files and the XSL for the toolkit.

Development went through the rigorous IBM process required to develop specializations. Boy, I sure love working for a small company!

The demoed pages and the description of the tagging looked like it would work for a basic, flat problem/resolution scenario. The XSLT provides standard labels for some of the section types, where for other section type(s?) there is a “label” tag that allows customized labeling.

For more complex decision-tree troubleshooting it would not work. Apparently this is Phase 2, currenlty under development, and Dan Dionne looked considerably more excited by the technical challenges in this phase than in the first phase. As he put it, “Specialization is absurdly easy.” Of course, he then followed this up with “Specializing DITA attributes is a shaky business.”

Hmm. Having just done same for a customer recently, I began to feel a little shaky.

One audience member opined that it would have been nice if IBM had removed the IBM-specific terms from the specialization before donating it to OASIS. The response was along the lines of “that effort did not fit into their business justification and they would applaud the contribution of anyone who wanted to expend the effort to make further sub- or up-specializations and donate it to OASIS.”

Well, sure, why not. It’s “absurdly easy.”

And that’s about it for tonight’s entries. I’ll try to catch up on today’s other four sessions tomorrow afternoon when the sessions have ended.

by David Kelly

Presented by Keith Schengili-Roberts from AMD, Inc., this session told the story of a successful implementation of a DITA/CMS solution. And that’s always a good kind of story to hear.

I don’t think there was anything unusual about the problem they were trying to solve. One thing it had in common with all the successful implementations I’ve heard about is that they had to translate their documentation into a lot of different languages — 25 or so. At lunch I asked the folks sitting at my table whether they were aware of any CMS implementations that had been justified by anything other than localization savings. No takers.

One analysis presented was why the addition of more writers was not going to solve the problem. I don’t have all the details of the analysis at hand, and this is a blog, where brevity is a virtue (though I do love to write in Russian novelist mode), so you’ll have to take his word for it. It doesn’t.

Some keys to their success:

* Meeting customers, getting their requirements for documents and delivery.
* Buy-in from management
* Working with the writers on the cognitive change to topic-based writing (training, etc.).
* Providing time for the writers to handle the extra overhead.
* Clear definition of roles. Engineers became responsible for correctness and completion of content, writers became responsible for clearness and consistency of content. To this point he mentioned that DITA allows tagging in multiple ways; editors are needed for tagging style.

He enumerated a large number of advantages that DITA provided, which I won’t repeat here. They chose Ixiasoft for the CMS, who later productized the customer DITA solution they developed for AMD (hope AMD got a price break). He did not mention they reasons for choosing Ixiasoft as far as I recall.

For an editor he began with the statement, “WYSIWYGs are detrimental to DITA.” This brought a rousing cheer of approval from Bruce Nevin, a Cisco Information Architect who was sitting right behind me. Keith said they chose oXygen, which I should have cheered since that is my own personal XML editor of choice. But then I do a lot of XSL development and I’ve always thought it was a little geeky for the average tech writer. Maybe Keith’s tech writers are like the folks in Lake Woebegon, Minn., who Garrison Keilor claims are all “above average.” Although when they had WYSIWYG editors, Keith said they were spending as much as 50% of their time on formatting. Whew, and I thought I was picky.

Keith presented several statistics to substantiate his claims of success. He was able to do this by relying on the reporting tools from the CMS, which he stated were significant aids to management in general. The statistics he presented were, for the most part, fairly abstract, but a couple stuck. One was the savings of 10% to 13% in localization costs. He admitted this was conservative, and it is indeed low compared to other claims I have heard, but he had included the purchase of Unicode fonts (Unicode in general was a big help) and the original conversion costs.
u
One success that he did not expect was that they doubled their output and halved the median project time. The localization savings were expected, but not the development savings.

In general this was a clear, astute, nuts and bolts presentation that gave a lot of information about the inner workings of a CMS/DITA implementation. Mr. Schengili-Roberts is obviously fond of metrics and objective data, so I suspect his claims were not exaggerated.

by David Kelly

Originally planned to be presented by Paul Wlodarczyk, this presentation was given by Amber Swope of Just Systems.

This session presented the possibility of structured documents that support a dynamic data link (I don’t think I mean that in the traditional sense) between the authoring/presentation layer and an underlying database. The purpose is to make documents “smarter” by allowing more interaction between the data and the user. One example would be something like a drop-down list inside a certain tag (say, a specialized market-segment tag). This would allow the author to select from a list of values that is maintained in a database. Another example might be a user selecting values from a set of queries, the result being a personalized document based on the answers.

In general this appeared to be a presentation of a solution that would need to be heavily customized by a vendor. It could be implemented for DITA or any other XML/structured data. But the concept certainly provides stimulus for thinking of a lot of possibilities. It’s late now and I don’t think I can think of any at the moment.

More tomorrow.

by David Kelly

This session was presented by France Baril from Ixiasoft. I think by this time in the afternoon I was starting to need a cheeseburger fix – and not a fast food joint in sight. For each point Ms. Baril presented what it was, when to use it, how to do it, and what to watch out for. Here I will only give a brief description of the “whats” in hopes that the curious will ping me (or her) about the whys and hows.

The 7 types of re-use enabled by DITA that she presented were:

1. Multiple output types from one source. XML to PDF, HTML, etc.

2. Using the same topic in different projects and contexts. Basically, multiple DITA maps can point to the same topic, but in different orders or with different selections of companion topics.

3. Regular conditional text/filtering. This is the standard DITA mechanism of specifying an attribute and value on a topic (or other tags), then including or excluding that text based on a setting in a ditaval file.

4. “Systematic” conditional text/filtering. I was not familiar with this term. I somewhat lost the definition, but it appears to involve the use of DITA-specialized elements combined with custom XSL. The example was the use of a list type. In documents for a given audience, the content of the list would be introduced by a title “Benefits” (provided by the XSL) followed by the list items. For another audience the entire section would be omitted from the document. This method was suggested for use only when certain kinds of information would be extensively re-used since the initial setup was likely to be expensive.

5. Conrefs – this involved the standard DITA use of conrefs, which basically involve creating a piece of text in one place, then “conreffing” it from another. In the final document the conref is replaced by the reference text. See my comment in an earlier entry about thinking about conrefs as contextless, stand-alone units of information. (Hmm, maybe if this blogging application application supported DITA I could have used a conref!)

6. Variables for words and phrases. She mentioned the tag. In general she seemed to think this method was problematic for localization (and even English-to-English re-use) due to grammatical/syntactical issues.

7. Automatic content creation. This one involves using some kind of processing system to essentially “reap” the source one or more times to create a secondary document. Some examples were references to Doxygen and Javascript, which make selections from programming source code to create documentation. She also mentioned the example of creating a table of contents in a Word document. And in fact I have written XSL to generate entire chapters that consist of, essentially, linked headings to descriptions of software commands, which are organized according to different criteria in each chapter. One source, many outputs, but in this case they are in the same format in the same document. And a host of other possibilities are out there…

by David Kelly

This session was presented by Sarah-Beth Doner and Laura Hood of RIM (the Blackberry people). I earnest beg indulgence not to present everything they talked about since there were two of them and they covered quite a bit of ground. Enthusiastically and authoritatively, I might add.

The central theme here was the culture shift required to get buy-in for a major change from being a Framemaker shop to becoming a CMS/DITA shop. Initially they made the change with a small committee selected from the first adopters, and after a small rollout project they began a larger rollout. Here they encountered pushback. Their solutions involved setting up groups and meetings to get broader involvement in the rollout and implementation throughout the entire user community. Apparently they had strong management support to enable the users to spend time on addressing the issues. As mentioned in a previous entry, they also found it necessary to begin redefining roles. Some roles they mentioned were mentor, support, tool development, and content enhancement.

Asked whether the democratic approach had resulted in any decisions that in retrospect they might regret, they agreed that there were instances where they made the wrong decisions, where tools were developed that they discarded, etc. But they found that it was important to keep everyone involved and informed to be able to make the system work – otherwise, apparently, the pushback was difficult to deal with.

Going forward, they are now at the point where enhancements and automation are the big pushes – the basics appear to be solved. (I believe they said they had been doing this for two and a half years.)

The benefits were mostly in reduced translation costs, the ability to scale from 8 language to 40 languages, the ability to customize documents per customer, and the quickness of turnaround time.

Another interesting question they answered: did the democratic process ever fail – how did they come to a decision when there were deadlocks, floundering, and indecision? They said that in general they had deadlines to meet, management expect certain answers by certain times, and if nothing else they had the managers to fall back on when they couldn’t arrive at agreement on their own.

(As a former documentation manager, I am pleased to hear that benign despots occasionally have their moments.)

by David Kelly

This session had a longish subtitle about open source wikis changing the face of technical publishing. It was presented by Peter Dykstra of MetaphorX, which is his consulting company.

The central point of this presentation seemed to be that Wikis had progressed to where they could be an easy entry into the world of CMSs, collaborative authoring, and XML -based outputs.
After an introduction to Wikis in general, he talked about the current state of Wikis. He listed the PHP-based Wikis (which he described as “cool”) and the Java-based Wikis (“IT friendly”). The list of functions now present in Wikis was surprisingly large – change management, versioning, role support, database back-ends, and infrastructure friendliness were some of the features I managed to jot down. (My notes also say “spoke very quickly.”) (And again, the salient talking points should be in the conference materials.) My sense of the functionality was that the Wikis should be considered more “document management” than “content management,” although he hinted that with planning and effort, a Wiki “document” could be fairly small, and therefore the management of documents could be fairly granular. (I eagerly await a robust demonstration of this assertion.)

He mentioned that he sees companies becoming much more receptive to open source applications than formerly. Wikis are becoming more popular, he says, due to the uncontrolled sprawl of Intranets. I’ve certainly seen THAT in more than one place. Of course, he also mentioned the sprawl of older Wiki sites he had seen. Supposedly the newer CMS-type functions help to control this problem.

With the use of a Wiki, he sees the opening of audience access to content and more collaborative information development. With the use of roles-based permissions, the writer can remain in control of the final output, but still take advantage of the richer input. One idea he suggested also came through in most of the sessions I attended – the changing roles of technical documentation professionals. In this case, the writer becomes more an editor than a content creator. He mentioned other roles – moderator, producer, online editor…

Finally, he gave a demo of Daisy, which is an open source Wiki (there are proprietary Wikis also available, in addition to the many open source Wikis.). It appeared to have some basic “book-like” features for concatenating topics, and the ability to define metadata for topics, and some conditional-type controls for topic inclusion/exclusion. What I call “topics” here were actually Wiki documents that he had defined to look like DITA topics. As far as he is aware, there is no full DITA solution currently available in an open source CMS.

So for all you Wiki open source developers out there, it looks like the field is wide open. Piece o’ cake!

by David Kelly

I am pleased to report that I made an error about making an error. Do those cancel out to mean I didn’t make any errors, or does it mean… well, never mind. Suffice it to say I won’t be able to blog “live” from the convention center during this convention, so I’ll be catching up in the evenings from paper notes. No hasty indiscrections here, I’m afraid!

I will try to keep it to one entry per session to make the blog more “topic oriented.”

Session 1, given by Eric Severson, CTO of Flatirons Solutions, had the promising title “Best Practices for DITA in a Global Economy.” Possibly due to the extensive (i.e., painful) experience I’ve had with DITA the past several years, I was disappointed to find that two thirds of the presentation was an introduction to DITA. This was surprising since Eric had asked for a show of hands from those who had DITA experience, and probably two thirds of the room raised their hands.

The final third of the presentation focused on re-use of information and the kinds of issues it raises for localization. He recommended a process similar to the one his company uses, which they call a “DITA Maturity Model.” This process is used to analyze legacy content to determine what kind of rewriting/restructuring is needed when converting to topic-oriented DITA source. One part of this involves a “content architecture” or information architecture phase to identify reusable information. This involves a fairly granular examination of the text to determine what content is identical, or close to identical, so it can be put into a form for optimum re-use. By all accounts I heard today, the payoff for this extensive, up-front architectural work is reduced translation costs and ease of maintenance. More about that in a later entry.

Some tips he passed along: When writing topics for reusability, think about them as having no context and therefore having to stand alone. Try to stick to the standard form of DITA if possible — “Specializations can cause problems” for localization. He also recommended not using conrefs haphazardly, but thinking from a perspective of “editorial integrity.” By this he meant avoiding conrefs to fragments of information, but making them more context-free, stand-alone chunks.

And even though I complain about the long introduction, I did later overhear someone saying she was glad he gave the introduction, otherwise she would not have understood the rest of what he was talking about.

by David Kelly

It appears that wireless access is available after all – a theory I have not yet tested, since I am now in the hotel room while they set up the conference rooms for the different tracks. We’ll attribute my earlier failure to connect to “user error.” I know, difficult to conceive…

JoAnn Hackos delivered the keynote speech for this, the 10th CMS conference, spending a good bit of time on the history of the development of content management, from the old days of human “code librarians” to the present. I won’t repeat her points, since I think they will be published elsewhere, but her take is that some of the current drivers for CMS implementation are:

* Minimizing the inventory of information for efficiency and ease of re-use.
* The need for collaboration rather than individual ownership of information.
* The need to capture and preserve the meaning/purpose of information by means of metadata.
* The need to secure, version, and compare versions of data.

She believes that these needs are starting to drive larger organizations toward “global enterprise content management” (GECM). She sees a movement toward wider adoption of CMSs – and standards – in the industry, a point emphasized by the 285 attendees and 17 countries represented at the conference.

Concerning the future, she did not offer any comments, but invited the audience to contribute thoughts about their needs to the conference blog (at www.cidm.com).

Having now delivered the first new-to-me acronym and a fuzzy, open-ended comment about the future, I will stroll down to the conference center again to try out the wireless connection. Take a deep breath…

by David Kelly

Greetings from lovely uptown Santa Clara, CA, where I’m attending the CMS/DITA North America Conference. I plan to make entries as often as possible, as it appears there will be a lot to hear and talk about. One limitation will be that there appears to be no wireless network coverage in the convention center, so the entries will be more sporadic than I had planned.

The attendance is planned to be around 280 people, and there are a lot of vendors from the content authoring, CMS, and services/consulting arenas. I’ve spoken with people from Vasont, CSoft, Ovitas, and Empolis so far, and we’re still 30 minutes from the conference being kicked off.

So far the consensus seems to be that DITA and CMSs are becoming well integrated. There are still issues of migration, seelcting vendors, specializations for various industries, and choices of authoring environments, among others. I’ll be keeping my ears open for perspectives on these issues, and I’ll pass along what I learn — as network access permits.