Core Dump

Although you probably wouldn't think of Word as a suitable tool for writing DITA topics, it is possible. One approach is to exploit Word's new XML-based .docx format and post-process the Word files in their raw XML state with XSLT. Elliot Kimber, aka Doctor Macro, has put together some XSLT code to do this and it's been released and is maintained through the DITA for Publishing project on SourceForge.

In a dita-users Yaho0 Group post yesterday, he said:

The system uses an XSLT transform that is driven by a style-to-tag mapping file to map DOCX XML files into arbitrary DITA maps and topics. We are using it for both the simple case of 1 word doc = 1 topic and one word doc = a sophisticated tree of maps and topics.

At the moment this is a one-way process, in that we have not implemented the reverse DITA-to-DOCX transform. However, that wouldn't be too hard to do using a similar style-driven approach. (There is a general DITA-to-InCopy/InDesign transform in the DITA2InDesign project that could be adapted to do DITA-to-DOCX since the business logic is similar although the data details are of course very different--but we haven't yet had a client requirement to round trip from DOCX-to-DITA-to-DOCX.)

The main limitation is the fact that it does require careful design of the Word styles to enable mapping to the appropriate DITA structures. It also doesn't handle in any sophisticated way the problem of mapping a flat sequence of character styles into a nested set of inline elements.

The project is at a very early stage right now so there's not a lot of documentation for it. He also appealed for help from DITA users to develop it further, so if you're interested, have a look. Given that Word is widely used in most organizations, this could be a viable approach to either extending the use of DITA more widely or at least being able to import Word content from other users into DITA projects.

Labels: DITA, Microsoft Word

If you've tried learning DITA by using the DITA Open Toolkit, you've probably figured you're doing things the hard way, and you are - unless you like running complex ANT scripts from the command line. There are tools to make using the Toolkit easier. Tony Self's WinANT has been out for a while. Now there's another front-end to the DITA Open Toolkit - this one simply called the DITA Open Toolkit GUI. It's written in Java and is open source.

I haven't been doing anything with DITA recently, but Leigh White has and posted a review of it on the DITA users Yahoo Group. Here it is, reposted with permission.

I just spent some time playing with this tool and find it a clean, quick alternative to the more complex Echidna/WinANT tool. DITAOT-GUI provides a simple interface, allowing users to select a map, DITAVAL filter, output location and output type. It bypasses the need to create a build file but therefore does not allow the use of parameters and properties to specify additional aspects of the build. Echidna/WinANT, on the other hand, does offer an interface to many of these parameters and properties and can create the corresponding build file on the fly. If you don't need the additional specifications offered by Echidna/WinANT, then DITAOT-GUI is an excellent, streamlined tool. I admit I did not find the Ditamap Composer to be very intuitive, but I didn't spend a lot of time with it.

There are several low-cost or free tools for ditamap creation, but very few for interfacing the OT. The real value of DITAOT-GUI seems to be more in its interface to the OT rather than as a map creation tool.

Labels: DITA, technical communication

Although DITA was originally designed for technical documentation, it's generic enough that it can be used for many other types of documents. This article by XML expert, Elliot Kimber, explains how.

This is the first in what will be an occasional series of DITA application discussions around the subject of applying the DITA standard to Publishing business problems (that is, using DITA-based XML markup as the source for documents produced by Publishers, as opposed to documents produced by product companies). Because DITA comes out of the technical documentation domain (it was developed by IBM as their next generation XML application for technical documentation, especially documentation delivered on the Web or as online help), most of the practical information about DITA reflects technical documentation applications.

But DITA is equally applicable to many Publishing applications, including traditional narrative documents that don't seem, at first look, like candidates for ditification.

Labels: DITA, technical communication

Eddie VanArsdall has put together a detailed comparison of the XMetal and oXygen XML editors with respect to their DITA functionality. It's worth checking out if you're evaluating DITA tools.

Labels: DITA, XML

After a lengthy beta process, DITA Open Toolkit version 1.5 is now available. From Robert Anderson's post on the DITA mailing list:

It is with great pleasure that I'm announcing the final build of the DITA
Open Toolkit version 1.5, now available to download from SourceForge! This
package has been a long time coming, and includes far more enhancements
than can be listed here; a few notable and recent enhancements include:
* Full support for the latest version of the DITA 1.2 specification;
* Many new enhancements, parameters, and fixes for PDF processing,
including the ability to override PDF with a plug-in;
* TocJS plug-in now shipped in the standard and full packages;
* Improved support for non-English character sets in RTF, and for mixing
languages in PDF;
* A sample Ant build script
(samples/ant_sample/sample_xhtml_plus_css.xml),
along with a small CSS file, used to demonstrate how to drastically change
the look-and-feel of XHTML output with a small CSS override.

There's a link to the download packages here.

Labels: DITA, technical communication

DITA 1.2, whenever it is officially finished, will have some major additions that will help authors work with glossaries. The DITA Adoption Committee has published a white paper that describes the glossary terminology specialization.

Labels: DITA, technical communication

The XML Mind XML Editor has been updated to version 4.5 and includes more DITA features and support. Especially interesting is the DITA Converter that they've bundled with it.

DITA support is now bundled in XMLmind XML Editor. This support has been greatly enhanced. It is now as comprehensive as DocBook support in XMLmind XML Editor. Most of the enhancements come from XMLmind DITA Converter.

XMLmind DITA Converter (ditac for short) allows to convert the most complex DITA 1.1 documents to production-quality XHTML 1.0, XHTML 1.1, HTML 4.1, JavaTM Help, HTML Help, PDF, PostScript®, RTF (can be opened in Word 2000+), WordprocessingML (can be opened in Word 2003+), Office Open XML (.docx, can be opened in Word 2007+), OpenOffice (.odt, can be opened in OpenOffice.org 2+).

XMLmind DITA Converter is free, open source, software licensed under the very liberal terms of the Mozilla Public License version 1.1.

Labels: DITA, software, XML

The latest version of DITA (Darwin Information Typing Architecture), DITA 1.2, is close to release. Here's a presentation (PDF), that covers the key features of the new release.

Labels: DITA, technical communication

One of the problems with using DITA and the DITA Open Toolkit has been getting everything set up and running properly, and then finding the best, most recent documentation. That's gotten a lot easier, at least if you're a Windows user, with the release of the DITAInformationCenter.

The DITAinformationcenter is a learning and prototyping package that
contains:
- XHTML and PDF versions of the documentation
- DITA Open Toolkit 1.5 (current beta level)
- PHP interpreter 5.1.4
- A number of PHP-based debugging, editing, and reporting tools
- Two sets of sample DITA projects: garage and grocery shopping
- A README file explaining how to install and use the package
- DITA source files for the documentation (.zip file)

If you've looked at the DITA Open Toolkit User Guide in the past some of
this will sound familiar. What's new is that the key tools that will get
you started with DITA and the Toolkit are packaged together as a Windows
.msi file (easy to install and use); the documentation and tools have been
thoroughly updated, streamlined, and improved; and the package works and
has been tested at the Toolkit 1.5 level (although the content and tagging
do not yet contain 1.5-level features).

Labels: DITA, technical communication

The Rockley Group has officially launched their new book, DITA 101.

We’ve designed DITA 101 for writers and managers. We’ve taken our years of experience helping organizations to move to DITA and distilled it into an easy-to-read and understandable format. And since the move to DITA often goes hand-in-hand with an organization’s adoption of content management, we’ve made sure that our expertise in developing effective content, reuse and content management, and their appropriate strategies are integrated throughout to give you everything you need to know to understand DITA.

DITA 101 is written for authors who need to understand the concepts but don’t need to know how to set up DITA nor how to modify the code. This book is about understanding structure, structured writing and reuse all in the context of DITA. In addition, we’ve also written DITA 101 for managers to help them understand the basics of DITA, the changes in roles, and the things to think about when planning a DITA project.

You can read my recent review of DITA 101 here, and the Content Wrangler has just published a review.

Labels: books, DITA

The DITA Technical Committee is busy trying to get DITA 1.2 released, and they've started to issue articles about some of the new features in the upcoming release. The first is about keyrefs, which will allow indirect addressing, making it easier to reuse content.

DITA 1.2 introduces the "keyref" feature which provides an indirect addressing mechanism. You can use either topicref elements or keydef elements (new with DITA 1.2) to define keys in a DITA map. Topics can now be given a symbolic name (keys attribute) that points to a topic file path (href attribute). Future references to such topics are made using a key reference (keyref attribute). At a later point in time, if the topic is relocated, the path needs to be updated only in the map where it is defined. All other references will automatically pick up the new location.

Labels: DITA

One of the major new features of MadCap Software's Flare 5 is DITA import and export. Scriptorium's Palimpsest blog has a two-part review of Flare's DITA capabilities (Part One and Part 2)

The import feature seems to work pretty well, as long as you haven't specialized DITA (which Flare doesn't yet fully support). This capability should give DITA authors a fairly easy way to generate full web-based help systems from DITA source files. (WebWorks ePublisher has offered the same ability since 2007), as well as PDF output that's better than that offered by the DITA Open Toolkit.

I haven't yet seen a discussion of Flare's DITA export feature. Given that MadCap didn't demo it in the webcast of Flare's new features, I suspect that it's more complex to use than the import, which appears pretty straightforward.

Labels: DITA, MadCap., technical communication

DITA 101: Fundamentals of DITA for Authors and Managers; Ann Rockley, Steve Manning, and Charles Cooper; The Rockley Group, www.rockley.com, 2009, 138 pages, paper, $9.95 (download), $25.21 (paper)

Since its introduction in 2001, DITA (Darwin Information Typing Architecture) has become the dominant standard for structured authoring. According to a recent survey conducted by Scriptorium (results discussed in this presentation), about 70 percent of respondents working with structured authoring are either using DITA now or planning to on future projects. That's pretty impressive for something that wasn't much more than an inscrutable article in Technical Communication and some poorly documented Java/XSLT code eight years ago. Yet structured authoring represents only part of the technical communication field; according to the same survey, 29 percent of respondents are using structured authoring now, more than half plan to do by 2010. That means there are many potential users of DITA who are likely going to be searching for information about it sometime in the future.

One of the barriers to implementing DITA has been the state of its documentation. Like many open source projects, DITA's documentation is scattered and inconsistent. The documentation for the DITA Open Toolkit has improved dramatically in the last few years, but it still isn't up to the standard of most commercial projects. Comtech Service's Introduction to DITA, first published in 2006 and recently updated, offers a good introduction to getting started with the DITA Open Toolkit, but may be too technical for many writers, especially those who just want to use the DITA implementations that are now included in most major writing tools.

DITA 101: Fundamentals of DITA for Authors and Managers, a new book from the Rockley Group, provides a more readable introduction. Rather than explaining the nitty-gritty of how to use the Open Toolkit and XML, it focuses on explaining what DITA is (and isn't), and what are its benefits and pitfalls. Much of the books content comes from experience the members of the Rockley Group have gained in conducting training DITA and content analysis and management.

The book begins with a history of DITA and the use of XML in structured documentation, then looks at the benefits of structured authoring. The primary benefit is the ability to separate format from content, thus making it practical to reuse content in different contexts. The authors provide practical guidelines for writing structured content and discuss the different ways of reusing content, all before getting into a discussion of DITA itself. This is followed by a review of the DITA topic types, concept, task, and reference, with an explanation of the elements that make up these topics.

Planning is especially important in a DITA project and the book contains a chapter explaining the key steps, including a summary of the Rockley Group's unified content strategy (explained in much more detail in Rockley's other book, Managing Enterprise Content). The authors also spend some time discussing an issue that is often neglected when organizations move to a structured workflow - how the authoring process changes the organization and the effects it has on people's roles. One area that is given rather short shrift is content conversion - they recommend against it, but this may not be practical in organizations with a lot of legacy content. I would have liked a discussion of some of the issues and alternatives here.

The technology involved in implementing a DITA-based workflow can be quite complex and daunting. The authors provide a succinct discussion of the issues, including when and how to use DITA with a content management system.

A section called "The advanced stuff' looks at conrefs (which provide content reuse), conditional processing, relationship tables, and specialization, which is DITA's mechanism for customization. Finally, a set of Appendixes contain a reference to DITA topics and elements.

Although this isn't a long book (140 pages), it's full of useful information, tips, and guidelines. The Rockley Group is an industry leader in the area of structured authoring and content managment, and they've distilled a lot of their experience into this book. Writers contemplating a move to DITA should definitely read it, and give a copy to their managers, too. At the very reasonable price of $9.95 for the download edition, this book is a bargain.

Labels: books, DITA, technical communication

Syntext is making available a free version of its Serna XML Editor. Serna renders documents in a WYSIWYG mode using XSL-FO and supports major XML standards, including DITA. The free version lacks support for content management systems and other enterprise-related features.

Labels: DITA, software, XML

Elliot Kimber (aka Dr. Macro), has created a new DITA project, DITA for Publishers to address some of the shortcomings that make DITA diffult for traditional book publishers to use.

Publishers are starting to take DITA very seriously and Really Strategies has been in the forefront of that trend as champions of Publishing requirements on the DITA Technical Committee and within the larger DITA community, as practitioners developing solutions and approaches for applying DITA to Publishing business problems, and as tool developers creating software solutions that support the Publishing use of DITA.

Out of the work that we've done over the last couple of years we have developed a number of basic Publishing-specific DITA components that are completely generic. We also started to realize that for Publishers to realize the maximum value from their use of DITA there would need to be a common starting point that Publishers could leverage, avoiding the need to re-invent things everyone needs. Eventually Publishers will need formal representation in the DITA standardization process, once there is sufficient Publishing community involvement.

You can find out more on the blog post linked above, or at the project's SourceForge site.

Labels: DITA, technical communication

When I was at the Content Management Strategies conference in 2006, I bought Comtech Services new book, Introduction to DITA, and spent part of the summer working my through it to gain an understanding of what DITA was about. The book certainly helped me learn the basics of DITA. Now Comtech has introduced an electronic version of the book. The price is $45.00 USD.

Comtech Services, with the assistance of Eurofield Information Solutions, has released an electronic version of the popular Introduction to DITA. The eCompress version allows you to read online, search for content, add bookmarks and notes, and send notes to other subscribers. We can also send updates to everyone who has a copy. The electronic version is designed for use on one computer and allows you to cut-and-paste the XML code samples into your own documents.

Labels: DITA, technical communication

Adobe's Technical Communication blog has a long post explaining how to specialize DITA in FrameMaker 9. Specialization is one of DITA's most powerful features, and wasn't easily done in FrameMaker 8. (It's probably not easy no matter how you do it, but that's another matter).

Specialization is the process by which new designs are created based on existing designs, allowing new kind of content to be processed using existing processing rules.Specialization allows you to define new kinds of information (new structural types or new domains of information), while reusing as much of existing design and code as possible, and minimizing or eliminating the costs of interchange, migration, and maintenance.

FrameMaker provides special handling for many objects in DITA like Table, Image, Title, Indexterm, Xref etc. so when we specialize any such element which have some special handling, same handling should be available for it. E.g. When we insert a crossref in any DITA document (xref or fm-xref element from element catalog or Special->Cross Reference), DITA-Cross reference dialog shows up. Same should happen if we insert any specialized xref element in any DITA document and name of specialized element should also show in DITA Element drop down.

Labels: DITA, FrameMaker

Writers who look at DITA are sometimes put off by it's apparent complexity, and decide not to use it. Or, they may decide that because it appears to be designed for technical manuals, that it's not suited for documents like a company report. Elliot Kimber looks at this and offers a reality check.

DITA is a sophisticated application architecture with lots of very useful features. People coming to DITA or promoting it, especially in the TechDoc world, tend to focus on the most sophisticated features because they're focusing on business problems for which those features are intended, such as managing large bodies of small re-used information modules across information for many products (for example, mobile phone manuals). That's cool stuff, but it's also pretty complex. It's no suprise that people see in-depth discussions of DITA maps and re-use strategies and localization best practice and say "hold the phone, I just want to get my traditional documents into XML I can understand--I don't need all this fancy stuff."

I'm here to say: you're probably right, you don't need all that whizbang stuff (today), but don't be so quick to reject DITA as a potential solution base.

If you ignore all of the features of DITA that get the technology guys like me excited, you start to see that DITA has two important aspects that tend to get overlooked:

1. At its core DITA is very simple and can be easily applied to simple XML applications that just need to represent things like books and magazine articles.
2. DITA's unique extensibility architecture makes it a much better business value than any comparable XML alternative.

Labels: DITA, technical communication, XML

Adobe's Technical Communication blog has a long post about using DITA maps in FrameMaker 9. The post includes several embedded demos.

Labels: DITA, FrameMaker, technical communication

One of the DITA mailing list members has created a Twibe for DITA. What's a Twibe, you may ask?

rom www.twibes.com...
What is a twibe?
A twibe is a group of Twitter users interested in a common topic who would like to be able to communicate with each other. On each twibe's page, there is a list of twibe members. There is also a tweet stream that lists tweets from twibe members which contain key word tags. You can browse through twibes that have already been created by going to www.twibes.com/twitter-groups.

I could see twibes being useful for a lot of things, but maybe not DITA, given the length of some of the messages on the DITA mailling list.

Labels: DITA

Practical DITA is a short introduction to DITA written by Julio Vasquez. My co-worker, Scott Nesbitt, brought back a copy from DocTrain West, and I had a quick look at it. From what I could see, it would serve as a good introduction to DITA for a writer not familiar with the subject, but it didn't go very deep.

XML Press has reviewed the book and come to much the same conclusion.

Overall, I think Practical DITA is a useful book for readers who want to dip their toes into the DITA stream and get started. It could have used another editing pass, a little more meat, in particular some detailed examples, and the print formatting reveals some of the limitations in the current version of the DITA Open Toolkit. That said, I liked this book. It sets a clear goal, for a specific audience, and achieves that goal; that’s rare.

Labels: DITA, technical communication

chm2web is an application to convert compiled Microsoft HTML Help (.chm) files to a web-based format that any browser can read. While you might think that it's kind of superfluous if you're already using a help-authoring tool like RoboHelp or WebWorks ePublisher, there are a lot of legacy HTML Help files floating around large organizations, and in many cases the original source files aren't available. It's not free, but it is reasonably priced for a utility.

There's another possible workflow, which was suggested in a comment on the Yahoo Help Authoring Tools and Techniques group. You could use this tool to convert DITA-based files to good-looking web-based help. One of the limitations of the DITA Open Toolkit is that the XHTML output is pretty basic. It does, however, do a decent .chm file. You could write DITA topics in an editor or tool like FrameMaker, create a .chm file with the DITA Open Toolkit, and then use chm2web to build web-based help.

Labels: DITA, software, technical communication

Most modern text editors allow syntax highlighting of source code, and many developers prefer to have that maintained in code listings or other documentation. Now there's a DITA Open Toolkit plug-in that will let you do that.

Labels: DITA

IBM developers have released the DITADoclet for producing DITA-compatible Java documentation. Essentially, it produces output similar to the Javadoc tool, but in DITA format, so you can do a lot more with the output than with the output of the standard Javadoc tool. This IBM DeveloperWorks article tells you all you'll need to know to get started. I wish I had this when I was working at Daleen several years ago.

In this article, you will learn how to use DITADoclet, DITA Java API specialization, and the Eclipse IDE to create Java API reference documentation for easy distribution in many formats. DITADoclet generates the DITA Java API files, automatically creates the DITAMAP and MAPLIST files (DITA Java API specialization) for the Java API reference documentation, extracts the developer comments from the Java source code, and migrates the information to the generated DITA API files.

Typically, the Javadoc tool from Sun Microsystems is used to generate Java API reference documentation from Java source code. The Javadoc tool generates the basic structure for the Java API reference documentation, but the documentation is often incomplete and limited to developer comments. Changes to development teams appear to encourage removal of the API writers and editors from the Java API reference documentation process altogether. Developers have time to manage only Java source code files with incomplete comments. This situation clearly presents API writers and others who are interested in producing high quality API documentation with some substantial challenges.

The DITADoclet and DITA Java API solution provides API writers with the tools to generate fully documented Java APIs. A fully documented API can serve several purposes, but the most important reason is to allow the API users to fully understand, search, and browse the API functions that are available to them. To completely use the functionality of the API, software users require an accurate and fully documented API.

Labels: DITA, software, technical communication

Last week, Sarah O'Keefe presented a very good introduction to DITA as part of MadCap Software's ongoing webinar series. The webinar was recorded and is now available for viewing online - you'll have to register first. You can view just the slides on the Palimpsest blog.

Labels: DITA, technical communication

WordPress is one of the most popular blogging platforms. Now there's a tool that will let you import the XHTML output from the DITA Open Toolkit into a WordPress blog. As Tom Johnson points out, this fills a big gap, providing a good looking webhelp-like output format. Tom also provides a video that demonstrates the process.

Labels: DITA, software, technical communication

From what I can see, the biggest hurdle to wider implementation of DITA is the difficulty of getting high-quality output, whether PDF or HTML, using the DITA Open Toolkit. If you read the messages in the Yahoo DITA-Users group, for example, a large portion of the messages are about issues with the PDF transforms that come with the Toolkit.

Sarah O'Keefe discusses this on Scriptorium's Palimpsest blog.

I estimate that about 80 percent of our consulting work is XML implementation. And about 80 percent of our XML implementation work is based on DITA. So we spend a lot of time with DITA and the DITA Open Toolkit.

I'm starting to wonder, though, whether the adoption rate of DITA and the DITA Open Toolkit is going to diverge.

For DITA, what we hear most often is that it's "good enough." DITA may not be a perfect fit for a customer's content, but our customer doesn't see a compelling reason to build the perfect structure. In other words, they are willing to compromise on document structure. DITA structure, even without specialization, offers a reasonable topic-based solution.

But for output, the requirements tend to be much more exacting. Customers want any output to match their established look and feel requirements precisely.

Widespread adoption of DITA leads to a a sort of herd effect with safety in numbers. Not so for the Open Toolkit -- output requirements vary widely and people are reluctant to contribute back to the Open Toolkit, perhaps because look and feel is considered proprietary.

Update: Yikes, that's what I get for being in a hurry. DITA, DITA, DITA - not DOTA!

Labels: DITA, technical communication

DITA's conditional text processing is one of it's more powerful and useful features, but it can be difficult to set up. The Ditaval File Generation Utility is a free utility that's designed to make it easier to work with DITA's conditional attributes and ditaval files. It's Windows only and free.

This utility parses all the DITA files referenced in a ditamap file (including all conrefs in any file) and gives a list of all conditional attribute values found in product, platform, audience and otherprops. Using this list, you can check that all the values are valid and that there are no mistaken values. You can then choose which attributes to include and exclude, and automatically generate a ditaval file.

Labels: DITA

From the discussions on the DITA Yahoo group, the short description or shortdesc element in DITA seems to be causing people a lot of headaches. It's an important element to use properly and many people have trouble writing good short descriptions that are reusable in different contexts. Kristen Eberlein has put together a good presentation on the proper use of the short description, which is worth reading if you're a DITA user. And even if you're not, the tips on writing a useful short description can be applied to many other situations.

Labels: DITA, technical communication

As Scott Nesbitt points out, the words Return on Investment (ROI) strike fear into the hearts of many, especially if you have to justify the cost of a new piece of software, or worse, your own job. Content reuse, especially using DITA (Darwin Information Typing Architecture) is often cited as way of improving the ROI of documentation projects.

Now The Content Wrangler has published an article by Mark Lewis that provides cost metrics for a DITA-based project. By doing some content analysis on your own projects, you should be able to estimate whether DITA will save you money. From a quick review of the article, it looks like you could apply the technique even if you're not using DITA, but using a topic-based tool like MadCap Flare.

he most important things we accomplished in this paper included determining the cost of creating a DITA-based topic rather than a traditional page. We then incorporated conditional reuse/filtering and determined the average cost of creating a reusable master topic. We observed that the biggest savings resulted when reusable master topics are incorporated. The flexibility and diversity of conditional reuse in DITA differentiate it from typical help authoring tool technologies and offer greater savings in not only content creation, but also content maintenance.

Labels: DITA, technical communication

The stand-alone version of Mylyn WikiText is available for download. I had a quick look a the documentation for this and it looks like it should allow the exchange of DITA content between Confluence and MediaWiki and a couple of other formats. You will need some familiarity with Ant to run build scripts on the included .jar files.

I'm going to have to keep an eye on this - it looks like it may offer a solution for getting text out of our TWiki wiki at work, although we'd have to develop a structured FrameMaker DITA template to go with it.

Labels: DITA, technical communication, wikis

There's yet another attempt to add DITA support to wikis. Mylyn WikiText now can output DITA from wiki markup.

Mylyn WikiText provides a flexible architecture supporting multiple wiki markup languages. This provides organizations with many options when considering a DITA toolchain, whether it be a one-time conversion of existing wiki assets to DITA, or as an integrated part of a publishing process. Currently supported are MediaWiki, Textile, Confluence, TWiki and TracWiki.

I might have to take a look at this. It would be nice to be able to take TWiki markup and bring it into structured FrameMaker as DITA-formatted content.

Labels: DITA, wikis

As expected, MadCap Software have announced their plans for supporting DITA. It looks like they'll start with DITA import and work up to full DITA authoring capability. Details are on the MadCap DITA page. Bob Doyle's DITA Newsletter also has an article about it.

With MadCap Flare and Blaze, authors will be able to import DITA projects and topics as raw XML content, and using the XML editor, change the style sheets to get the desired look and structure.

Authors will then have the option to publish the output as DITA content; print formats, such as Microsoft Word, DOCX and XPS or Adobe FrameMaker, PDF and AIR; and a range of HTML and XHTML online formats. MadCap’s software handles the DITA transforms, so authors don’t have to. MadCap Analyzer will work directly with DITA topics and projects to allow authors to analyze and report on the content. Similarly, MadCap Lingo will import data directly from DITA topics and projects, so that it can be translated. The translated material can be published as DITA content or exported to a Flare or Blaze project.

Labels: DITA

Eric Armstrong from Sun Microsystems has posted a page listing some tips for customizing the output of the DITA OpenToolkit. While the DITA OT is functional out of the box, the output it generates is pretty bare bones. Based on some of the comments I've seen posted on the DITA Yahoo group, getting output to look the way you want it is the biggest problem most people have when using DITA.

Labels: DITA

If you work with large document projects, you may be considering making your documentation more modular, breaking it down into discrete topics, and re-using the content in various ways. Sun's Cool Stuff blog (infrequent, but always worthwhile) has published a couple of articles on the subject. The first is an overview of modular writing, the second compares the two leading technical communication methodologies: DocBook and DITA.

The ability to use topics written by others saves time when creating new works. That reuse will typically occur within a department, but it can also occur across departments, and even across organizations--given a common standard for document formats, which allows information to be interchanged. (Of course, the further the information travels from home, the more imperative for content to be separated from presentation, since the presentation format will undoubtedly differ in other departments and organizations.)

But note that there is a big difference between document components that can be reused, with a little work, as compared to components that are truly and simply reusable as they are. Modular components that already exist as independent entities are like Lego blocks. You can use one to create to an airplane or a boat. It makes no difference. Other information structures are more akin to model airplanes--the components could be reused, but only after you do the surgery necessary to extract them from their current setting. The degree to which additional effort is required is the degree to which reuse is impeded.

Labels: DITA, technical communication

If you're using DITA for online help, take a look at this post from Communications from DMN, which describes current efforts to make DITA more suitable for online help.

Labels: DITA, technical communication

Scriptorium have posted a downloadable version of their webinar, Key Elements on Customizing and Troubleshooting Output (or Hacking the DITA Open Toolkit).

Preparing for this presentation caused me to reflect on the work I used to do, modifying FrameMaker templates. In that work, I figured that 90 to 95 percent of the work was simple style replacement (update the decorations on the master pages, change the font in this paragraph style, add new character spacing to this character style, and so on). That was the easy stuff.

The remaining 5 to 10 percent of the work was the really hard stuff, often where the order of text items changed (building a challenging chapter opener, reimplementing admonitions, replacing cross-reference formats). These are the things that took the time and had me reaching for FrameScript and Advil (not always in that order).

Modifying output from the Open Toolkit is similar. The changes to CSS (or attribute sets), header and footers, basic page layouts, and so on are quite easy to do (whether you do them in XMetaL or directly). The place where you'll spend much more of your time and effort is where the content affects the layout, where order of content matters, or where you have specialized content. This is the realm of XSL and specialization.

Update: Oops - I've added the link.

Labels: DITA

The UA (User Assistance) Conference is going on in Edinburgh right now, and Gordon Maclean has some notes on the first day's presentations. The WordPrss0DITA plug-in looks especially interesting.

Session 3 - Sonia Fuga - DITA & WordPress Solution for Flexible User Assistance
A showcase style presentation of a stunningly simple concept. With a little bit of coding work (building a DITA importer to get XML content into the WordPress database), the team at Northgate offer a web-based help system which allows users to add their own notes and to vote for useful information, and which is can receive updates with new content with each release.

How? By using WordPress features. Notes are left as comments, votes are left using a WordPress plugin, and the updateable content is controlled by only allowing the customer (who has access to the WordPress admin screen) to create Pages, leaving the Posts controlled by Northgate. I use WordPress for this website, and spoke to Sonia in the evening to confirm some of the finer details. It’s a very clever use of WordPress, and I hope Northgate release their DITA importer to the open source community!

Labels: DITA, technical communication

If you've been working with DITA at all, you'll know that getting decent quality PDF output is probably the most difficult aspects of using DITA. Partly that's due to the immaturity of the tools, and partly it'd due to the inscrutability of XSL-FO (Extensible Style Sheet Language - Formatting Objects) - the subset of XSL that you use to get printed output.

RenderX, the makers of the XEP formatter used in the DITA Open Toolkit, have a good tutorial on XSL-FO that'll certainly help with this rather arcane subject.

This document gives a quick, learn-by-example introduction to XSL Formatting Objects. I don't discuss subtle details of implementation, but rather provide a series of examples of how to perform routine tasks with XEP — an XSL formatter developed by RenderX, Inc. It is not a manual of XSL FO (XSLFO) in general, and some examples given here may not work in other XSL FO (XSLFO) formatters, or give different results.

This tutorial was conceived as a means to facilitate reading of XSL 1.0 Recommendation of October 15, 2001. The normative text is available from W3C site: http://www.w3.org/TR/2001/REC-xsl-20011015/. You should obtain a copy of XSL 1.0 Recommendation, and refer to it for a complete description of objects and properties mentioned here.

Labels: DITA, technical communication, XML

Anne Gentle has put together a very useful reading list about DITA (Darwin Information Typing Architecture). If you're new to DITA, or don't even know what it is, this is a good place to start.

Labels: DITA, technical communication

Scott Prentice of Leximation has created a new resource for DITA and FrameMaker users - an online knowledgebase. You can filter articles by categories such as installation or authoring and select a version of FrameMaker (if you're interested in FrameMaker topics). Scott says:

I've created a knowledge base to help people with DITA/FrameMaker
issues. This is set up so visitors can register and add their own tips,
techniques, and troubleshooting info. It has initially been populated
mostly with questions from maillists, but I'm hoping that you'll add
your own items so this can provide quick answers to common problems.

Labels: DITA, FrameMaker

The advent of structured writing and methodologies like DITA is forcing writers to examine some of their cherished practices. Bob Doyle looks at some of these, including the glue text myth and the stem sentence myth.

Stem sentences in technical communication have long been considered a standard practice to introduce new content, especially steps in a task. The task stem sentence, generally consisting of a partial sentence such as “To start the machine:” , followed by "1. Plug it in.", "2. Turn it on.," etc., is not supported by any explicit DITA element in the DITA Task information type.

Labels: DITA

Anne Gentle recently attended a DITA User's Group meeting at which Elliot Kimber described the work he's doing on getting Adobe's InDesign layout program to work with DITA content. It sounds like he's getting somewhere with it. Her post links to Elliot Kimber's more detailed information about the process.

Labels: DITA

Stem sentences are those short introductions to procedures that you see in a lot of manuals (mine included). For example: "To set the opening price for a stock:", followed by a series of steps.

There's quite a debate in the DITA community about whether stem sentences are helpful in procedures. DITA doesn't include markup for them, although you can get around that with some creative use of tags. The dita.xml.org blog has a good summary of the issue.

Writers argue, however, that sometimes there is valuable, even essential information to present between the title and the step. You may have a pre-requisite that includes a warning or caution or a list of equipment. You may have contextual information that explains more about the task to be done so that the user understands the reasoning behind his or her actions. Generally, this contextual information should be kept reasonably short in the task. For more context, readers should be sent to a Concept topic.

As the pre-requisite and contextual information grows, some writers and editors argue for a stem sentence to repeat the task title. Others argue that this practice is unnecessary because the user knows by the numbering that the steps are at hand. The argument for the stem sentence grows as proponents argue that they often writer procedures that contain multiple tasks under a more general heading. For example, they may have several sequential tasks that must be performed in order to complete an installation. Why not use one large task to accommodate the subsets with stem sentences to divide the sets from one another?

Labels: DITA, technical communication

Elliot Kimber (aka Dr. Macro) discusses some of the issues involved in choosing between DocBook and DITA. His post is in response to an article by Richard Hamilton on the Content Wrangler site. Both articles make a stronger case for DocBook than I expected, given the current buzz about DITA. If you're planning on implementing structured authoring, both of these articles are essential reading.

Labels: DITA, technical communication, XML

Eric Armstrong has written about the higlights of the DITA CMS 2008 conference that was held last week in Santa Clara CA. I went to the 2006 conference in San Francisco and found it a very worthwhile experience. If you want to get an idea of what's going on with DITA and content managment, this is a good article to read.

And for more from the conference, check out the Palimpsest blog from Scriptorium, which also has write-ups on more than a dozen sessions.

Labels: content management, DITA, technical communication

Data Conversion Laboratory has published an interview with Bob Doyle, founder of the DITA Users site. He talks about DITA and what he thinks its future will be.

It may always be the simplest way to get into XML, but we'll see. As the standard for structured content, XML will be key in the future. Because DITA adds so many benefits, and some costs, to XML, organizations need to weigh the additional tangible and intangible costs, and the effect on return on investment when considering moving to DITA. This, I think, will determine the future of DITA. If organizations see a high ROI in things like using topic-based authoring, conditional processing, task-orientation, component publishing, information typing, minimalism, inheritance, specialization, and simplified XML, then we will see DITA grow.

Labels: DITA

The Palimpsest blog from Scriptorium is carrying a series of posts from the Content Management Strategies 2008 conference in Santa Clara, CA. I went to the 2006 conference in San Francisco and was quite impressed, so I'll be following these posts closely. So far, there are posts covering six different sessions.

Labels: content management, DITA

Lexmation has updated the DITA-FMx plug-in for structured FrameMaker, fixing some bugs and adding a few new features. They've also announced that the price will be $185 for a single license, with discounts available for quantity purchases. The beta is still free if you want to check it out.

Labels: DITA, FrameMaker

One of the key selling points of DITA (Darwin Information Typing Architecture) is that it can be specialized, or extended, to include new types of data that aren't included in the core DITA. Most specializations are extentions of the ones built into DITA, such as user interface terms or highlihting. However, to create a specialization you have to modify some fairly complex XML files.

The DITA Specialization Generator is a web-based form that will get you started by creating the DTD and MOD files from your form input. It will certainly make it easier to get get started with DITA specialization.

Labels: DITA

Michael Priestly writes about a very interesting project from Lotus (now owned by IBM), to produce dynamic content using DITA.

There's a pilot project out of Lotus using DITA for dynamic content publishing, and you can also see the DITA source for any of the content in the project. You can search DITA source and return maps and topics. You can turn a search result list into a map that you can publish as HTML or PDF, or you can use a shopping cart mode to select content from multiple searches and create a more custom map for publishing to PDF or HTML.

A couple of upfront caveats: this is a pilot project, so expect some rough edges and some relatively slow processing (this isn't running on big iron). Also, the DITA source is preprocessed to make it ready for final-stage publishing, which means you won't see any conrefs in there, and you will some debugging attributes like xtrf and xtrc that you should ignore.

Labels: DITA

Getting a standard format for error messages is always difficult. Every developer seems to have a different idea about how to write and call error messages. Now there might be a way of getting everyone to agree on a standard format. The DITA message specialization has been releaed as a plug-in for the DITA Open Toolkit.

Message topics provide descriptions of the messages that a program or
system issues. Using the message specialization will help ensure
consistency and accuracy across all of the messages in a library.

Users refer to message information to understand what condition or event
generated the message and to find out what actions to take to proceed, to
recover from a problem, or to prevent a problem. Typically, message
information includes a description of the event that generated the
message, the possible causes, and suggestions for recovery actions. The
message topic contains details to help identify the particular problem and
includes responses for different types of users or different environments.
User response sections are provided for audiences such as administrators,
system programmers, or end users.

The message specialization creates a new topic type with a root element of
msg. The message container elements have standard labels that are
generated in a fixed order. Some of the elements are optional, some are
required. For more information on the message specialization elements,
read the usage information that is provided with the specialization.

Even if you aren't using DITA in your documentation workflow, getting developers to write error messages in this format. You can always use XSLT to convert the DITA source into another format.

Update: Sorry, I posted the wrong link. It should be fixed now.

Labels: DITA

The Rockley Blog looks at a couple of recent blog posts suggesting that DITA isn't a panacea, and points out some things you might want to consider if you're thinking about adopting DITA. For example:

# Free tools are not always the best tools – output

Your job is to produce user guides, help systems, training material, etc. It is not merely to produce topics. The tools you use to create PDF and CHM files is as important as the authoring tool you use. If you have no money, but can code XSL stylesheets or are willing (and able) to learn how to, the DITA Open Toolkit (free) sounds like a great choice. But if you struggled getting templates created when you installed FrameMaker, then the Open Toolkit might not sound so good. No matter what you choose – and there are alternatives to the Open Toolkit – you will have to spend time or money to get the outputs that you need, either in coding time for you to create stylesheets or in consulting time to have someone create them for you.

Labels: DITA, technical communication

DITA FM/x is a plug-in for structured FrameMaker that adds significantly to FrameMaker's DITA capabilities. Version 1.00 should be available soon, and you can find out more about it here. There's also a chart comparing FrameMaker's DITA support to what's currently available in DITA FM/x and what will be coming in version 1.00. Now if Quadralay would only release their patch to let WebWorks ePublisher with Frame 8, I could start thinking seriously about DITA again.

Labels: DITA, FrameMaker

Here's an example of the utility of DITA. Elliot Kimber has converted a section of the 1911 Encyclopedia Britannica (regarded by some as the best edition ever) from the Project Gutenberg XHTML source to DITA format. You can view the results (2 versions of HTML and PDF) here.

This data set makes a nice demonstration and test set. It's large, about
450 topics, and interesting, with graphics and footnotes and such, but
not gigantic. The markup I've generated is sufficient but not optimal,
so there's opportunity for cleanup or refinement or exercises in
specialization.

The entries themselves include some juicy stuff, including brewing,
bridges, and Buddhism.

The data is also well suited to interesting linking using reltables.

He's also converted the 1922 Outline of Science Note that the TOC in the frames version doesn't seem to be working.

This is the 1922 "Outline of Science", which I have marked up as a
"narrative" document, such that each chapter is authored as a single
top-level topic with nested topics. The document uses a bookmap rather
than a generic map. It offers a nice contrast to the Encyclopaedia
Britannica and offers more opportunity for testing and demonstration (as
well as linking, since there are probably interesting relationships
between the encyclopaedia entries and the outline of science stuff.

Update: Elliot Kimber has set up a repository for DITA conversions of Project Gutenberg material and is encouraging people to contribute.

Labels: DITA

Elliot Kimber (aka Dr. Macro) has started a project to convert DITA XML files to Adobe's InDesign. It's at a very early stage of development, but he's hoping to get involvement from the DITA community.

There's nothing much there at the moment, just a little bit of XSLT code
that demonstrates the general approach I'm taking for generating XML
that can then be imported more or less directly into InDesign CS3. (It's
just in the Subversion code repository at the moment--I haven't gotten
as far as building a separate distribution package).

This is intended to be a community project and I am actively soliciting
participation and contribution from anyone and everyone. While I am
authorized to contribute to the development, it will definitely be a
"spare time" project for me, at least for now.

I will be adding documentation and some Web pages to the project over
the coming weeks as I can.

My intent with this project is to develop a Toolkit plugin and
supporting InDesign scripts and templates that enable publishing
DITA-based content to InDesign with up to 100% automation. I say "up to
100%" because with InDesign there is usually an implicit expectation
that you may need or want to tweak things by hand. But there should be a
class of non-trivial page layouts that can be laid out 100%
automatically given a reasonable level of scripting effort.

Labels: DITA, XML

Elliot Kimber (aka Dr. Macro) writes that he's been helping the Financial Accounting Standards Board (FASB) develop an online version of the Generally Accepted Accounting Principles (GAAP), using DITA. There's more about the application on the Really Strategies Blog.

Given the foregoing, the FASB realized that a more traditional XML application, while possible, would not necessarily be optimal and would likely be prohibitively expensive and would not meet the requirements of licensees for ease-of-use of the XML content.

However, a DITA-based application would satisfy all these requirements. David Prather at FASB realized that the GAAP content could be modeled quite handily using DITA with some GAAP-specific specializations.

Labels: DITA

The Dita Users site now offers a free account, which gives you access to the online Dita Storm editor. This is probably the easiest way to get into using DITA. Getting one of the paid accounts will get you additional benefits, such as a copy of the Oxygen XML editor.

Labels: DITA

DITA-FMx v.02 has been released. DITA-FMx adds DITA functionality to FrameMaker 7.2 - it's essentially an improved version of the Application Pack that Adobe released before building DITA functionality into FrameMaker 8. The update adds new features, including a book-building capability, and fixes quite a few bugs. Since Adobe discontinued the Application Pack with the release of FrameMaker 8, this is about the best way Frame 7.2 users can work with DITA.

Labels: DITA, FrameMaker

If you start working with DITA, one of the first things you're going to run into is that you don't write manuals, you build them, and the tool you use to do that is the DITA Open Toolkit. It's gotten a lot easier to use since the first release, but it can still be ... tricky, especially if you aren't familiar with software build tools or if you need to go beyond the basic, built-in settings.

However, help is at hand. First, there's the DITA Open Toolkit User's Guide, which is the first document you should read when you start working with DITA. It explains how to install the toolkit, explains how to create and process DITA files, and includes both examples and sample files. The latest version, which has been updated for version 1.4.1 of the toolkit, has just been released.

Second, Alex Griesse at Webnextix has created a web-baesd GUI for the toolkit, that should make life easier for many users. He says:

Building a Manual? Well, there’s something you never thought you’d be doing with your documentation, I mean, what happened to just writing and saving the thing? This is the 21st century right? Sure you have some commercial initiatives on the go ( a few good open source ones too ) which try to ease the process. Subjecting users to the intricacies of the command line and technical details behind hand-crafted ANT target files without getting some blank stares has been a challenge in my experiences.

You can find out more about it in this post at dita.xml.org. It's similar to Tony Self's WinANT for DITA, which came out a few months ago, in that it provides a GUI-driven front end to the command-line interface of the toolkit. Either tool should make the DITA Open Toolkit much easier to use.

Labels: DITA

This post is triggered by an article of the same title by Gordon McLean, a technical writer in the UK, who takes a jaundiced look at some of the hype surrounding DITA. He says:

All of my research suggests that, rather than being a simple installation and conversion process, creating a DITA solution requires a lot of technical know-how and a not insubstantial amount of time and resource. We can handle the first, the latter is (I believe) not yet at a level which makes it cost-effective.

Ultimately, for the moment, DITA costs too much.

I was going to comment on this at length, but Scott Nesbitt beat me to it. We were talking about this at work today and I think Scott's pretty much captured the content of our discussion and expanded on it.

Don’t get me wrong. I have nothing against DITA. It’s a powerful tool, and definitely has its place. As do DocBook, FrameMaker, AuthorIT, and every other single-sourcing tool or approach out there. Each has its merits, and each has its drawbacks. But there is no ultimate solution to the problem of effective single sourcing. What’s right for one organization definitely can’t be effectively shoehorned into the needs of another.

From my experimentation with DITA, I see three major obstacles to implementing a DITA-based workflow. The first is that it's hard to get good quality printed documentation and in a lot of organizations, print is still the king. I really don't want to become an XSL-FO guru to have to get a PDF of a manual. At the moment it looks like writing DITA topics in structured FrameMaker is the best way around that limitation, but using FrameMaker adds its own set of issues.

The second obstacle is that DITA isn't really suited for online help. For a good explanation of why not, see the links in this post. Sure, you can now use WebWorks ePublisher with DITA files, but now we're back to using proprietary tools again.

Finally, there are all sorts of organizational issues, some of which McLean hints at in his post. In an organization that's print-oriented and struggling to implement document management, moving to a structured-authoring workflow that might also involve content management is a big step, and it's one that's not likely to succeed unless you're very good, very lucky, and have a lot of help.

But DITA still holds a lot of appeal and I'm going to keep nibbling around the edges. Writing in DITA isn't really that hard, but getting to the next level is difficult. Perhaps the next generation of writing tools will make it easier for small writing groups and lone writers to take those first, hard steps.

Labels: DITA

If you try to produce neatly formatted documents from XML files, you've probably run up against FO (Formatting Objects) and XSL-FO. It's not for the fainthearted. However, there is an alternative, called Prince XML, that lets you get neatly formatted PDF from XML or HTML documents using CSS and not FO. It's not free, although they do offer a free license for personal, non-commercial use. There's an article about it on Linux.com.

I settled on an application called Prince that specializes in converting XML to PDF. While proprietary, it is relatively inexpensive, runs from the command line on Linux and Mac OS X and as a GUI app on Windows, and has many advanced features not available elsewhere. It uses standard CSS to control formatting instead of something like XSL templates or LaTeX markup. In addition to pure XML, Prince can create PDFs from [X]HTML. It supports common image formats such as JPEG, PNG, TIFF, and GIF and a subset of Scalable Vector Graphics (SVG). By default, Prince uses the free Microsoft True Type fonts, available for Linux on SourceForge.

There's also a review of it on the O'Reilly site. There was some discussion about it on the DITA Yahoo group recently, as a possible alternative to the XSL-FO processing pipeline that the DITA Open Toolkit uses, but so far I don't think anyone has got that working.

Labels: DITA, XML

The XML 2007 conference was held in Boston last week. This page has an overview of the DITA presentations at the conference and this one has links to several writeups about the conference.

Labels: DITA, XML

The Rockley Group blog has more on the recently announced initiative to extend DITA for use with general business documents. Quite reasonably, they've decided to narrow the scope a bit, and start with "narrative" business documents. I still think it'll be a major undertaking.

We are focusing on narrative business documents. Even with a narrower focus we realize that there are literally thousands, if not thousands and thousands of different types of business documents. Our first tasks are to:

* Identify relevant business process use cases to determine where a structured content/DITA solution might fit.
* Identify potential documents
* Create use cases for sample documents

From there we hope to create a meta-model for a narrative document. A meta-model is like a generic model that can be used as the basis for the actual DITA modeling work. This means that we will analyze documents and try to define the underlying structure. This seems like an impossible task when you think of all the different types of business documents, but it isn’t really. Let’s take existing DITA for a moment, when analyzing all the different types of technical documentation whether it was for software, hardware, boats, medical devices. You begin to see repeated structures over and over again as you look at the information. This is how the generic task, concept, and reference topics were identified. The content is different, but the structure is the same. We anticipate that there will also be common structures in the business documents.

Labels: DITA

Back in March, I posted about a paper written by Tony Self in which he looked at using DITA for online help and found it lacking in some key area. Now, some of these shortcoming may be addressed with the formation of a subcommittee of the DITA Technical Committee that will focus on online help.

The aims of the DITA Help SC are to:

* develop a top-level design for authoring of Help systems and user assistance content for implementation using DITA;
* establish recommendations for the integration of DITA-authored Help systems and software applications using context-sensitivity;
* remove the obstacles to effective use of DITA for Help systems through the creation of best practice guidelines, cookbooks and worked examples, and to promote the use of DITA for creating Help systems and user assistance content;
* develop informal support for processing DITA for delivery as Help systems and user assistance;
* establish guidelines that promote best practices for applying standard DITA approaches to Help systems and user assistance content. The deliverables of the DHSC will be:
* recommendations to the DITA TC for specification changes to better support Help systems and user assistance content;
* a high-level processing model description that defines the standard use of DITA for Help systems and user assistance content;
* explanations and guidelines for the use of DITA for Help systems and user assistance content.

Labels: DITA, video

A new OASIS subcommittee has been announced that will try to expand DITA so it can be used for general business documents. One of the committee co-chairs is Ann Rockley, well known for her expertise in content management. This is an interesting initiative and one I hope succeeds as there's a real need for more structure in a lot of business documentation.

More and more enterprises (pharmaceutical, medical device, health and hospital, high tech, finance, government) are moving to structured XML content for many different purposes (marketing, sales, product usage and support) and applications (web, multichannel publishing, globalized content). A growing number of these organizations have come to believe that DITA not only provides the best basis from which to start addressing their requirements for narrative business documents, but one which will help them to achieve their goals faster and in a standardized manner. But because DITA was initially designed to address technical documentation challenges, specializations and workarounds have been required.

The subcommittee is looking for participants, so if you are interested in this or have expertise in the area, check it out.

Labels: DITA

A while back, I mentioned the Lone-DITA site, a site that provides information about DITA for lone writers, who often don't have the access to resources (XSLT programmers, for example) that larger writings groups do. I just had a look through their tutorial and it's excellent. If you're getting started with DITA, or just want to know more about it, this is a good place to start. You can view it online or download a PDF version. Sample files are also available.

Labels: DITA

Sun's Eric Armstrong has written one of the more interesting articles I've seen in a while, about the possibilities of using wikis for structured documentation.

Wiki systems make it easy to edit documents online. That makes them terrific for document collaboration. But current Wiki formats don't allow the kind of reuse that the DITA document format was designed for. But it may be possible to implement some of DITA's best features using a some clever combination of JavaScript and CSS. I suspect it can be done most easily using a Ruby-based Wiki like MediaCloth.

Labels: DITA, technical communication

The October meeting of the Boston DITA User's Group hosted a presentation on the Bookmap specialization in DITA 1.1 given by Amber Swope of JustSystems (think XMetal). Bookmaps are a new feature that make it easier to publish standard printed book-like elements (TOC, preface, etc.) in DITA.

The presentation is an embedded Flash file and is about an hour long. It has a TOC (click the page icon) and can be expanded to full screen in your browser.

Labels: DITA

A while back, Tony Self wrote a good paper on the shortcomings of DITA as a help-authoring tool. Now he's done a lot to address those shortcomings, by writing a Windows-based front end to Ant, specifically designed for DITA projects. Naturally enough, he calls it WinAnt, and you can find out more about it on his web site.

WinANT allows a user to select build characteristics using normal Windows interface devices such as dropdown lists, radio buttons, tabs and browse buttons. When all the required settings are in place, the program creates the Ant build file, creates a ditaval file (if required), creates a batch file, and then executes the batch file to trigger the Ant build. When Ant has finished the processing, WinANT displays the generated output file. The settings can be saved (as a build file) and later recalled.

If you're using DITA, and especially if you're doing builds from the DITA Open Toolkit, you'll probably want to check this out.

Labels: DITA

Sun's Eric Armstrong writes about using ODF as an intermediary between DocBook and DITA. The conversion is facilitated by a set of transformations from Flatirons Solutions; for more on these, see the presentation linked at the end of the article.

The ODF transforms are pretty interesting. They would make it possible to edit DITA or DocBook documents in OpenOffice--an open source suite of tools that is available to everyone. That's a far cry from the kind of money you have to spend to get a really good editor these days. (Those editors will still be needed for handling content references, at the very least. But it will be interesting to see what can be done using OpenOffice.

But it's the DITA/DocBook transforms that are of most interest for interchange with legacy systems and tools. (There is also the question of how they handle DITA content references and DocBook entity references. But that's one of the tricky details that a concept paper like this can skim over...)

Unfortunately, it's those tricky details that keep people like me from adopting DITA right now.

Labels: DITA, XML

DITA architect Don Day has put together a very useful page that lists resources for the DITA Open Toolkit. As well as links to the toolkit and user's guide, it describes the currently available plugins.

Labels: DITA

Leximation and Silicon Publishing have released DITA-FMx, an updated DITA plug-in for FrameMaker 7.2. Basically, this replaces the FrameMaker-DITA application pack, which is no longer available through Adobe. It adds some new features and fixes some bugs that were in the original application pack.

DITA-FMx fixes/updates the following ..

- the provided structapps fix all known bugs
- FrameMaker variables will now round-trip properly (and work in OT
output)
- spaces are no longer randomly deleted from indexterms
- works properly with read-only files (like for conrefs)
- image attributes and FM properties toggle each other
- conrefs and topicrefs are no longer colored with conditional text ..
meaning that you can actually use conditions to do filtering in Frame.
- conrefs to table parts work properly
- tweaks to make it work better with CMSes (especially XDocs)
- misc other cleanup

They plan to release a version that will be compatible with FrameMaker 8. DITA 1.1 support will also be added.

Labels: DITA, FrameMaker

Version 1.4 of the DITA Open Toolkit has been released. This release supports the new DITA 1.1 specification.

The DITA-OT Release 1.4 contains full support for the OASIS DITA 1.1
standard. This completes the preliminary support added in the 1.3 and
1.3.1 versions of the toolkit. New and improved items for 1.1 are listed under
[Improvements] below. Support for the new bookmap standard is available in
the latest version of the FO plug-in, which uses the "pdf2" transform
type; it will be released together with or soon after the release of DITA-OT
1.4. The deprecated "pdf" transform type has not been updated for the new
bookmap.

Labels: DITA

The folks at ditausers.org have set up another DITA resource, this one a wiki. As well as a glossary, there are topics for the new DITA 1.1 specifications and quite a few other topics. Content in some areas just consists of placeholders -- this being a wiki, they hope readers will add the content.

Labels: DITA

Eric Armstrong of Sun has published a review of the XDocs CMS (content management system). He likes it quite a bit. It's relatively cheap, as these things go, and it supports DITA. Oddly, for a documentation-related product, the documentation comes up lacking.

Labels: content management, DITA

It's a sad fact of life that many technical writers (including me) are stuck with using Microsoft Word for projects where a more robust tool would be a better choice. Working in XML, or converting your files to XML, might solve some of Word's many issues. Bob Doyle has written an article about converting Word to XML.

An easy way to begin, one that content contributors may be comfortable with, is consistent use of the same Word templates for the same document type. Of course, they would then still be free to deviate from the template, which will cause problems down the road.

So there is a new class of tools that look exactly like Microsoft Word, but which can force your authors to create perfectly structured documents. By perfectly structured, we mean that when exported to XML, the document can be validated against a DTD (document type definition) or XML Schema Document (XSD).

Microsoft has provided an API that allows developers to customize Word. They can selectively disable Word's menus to allow only those options that are valid at a given point in the document (context-sensitive controls).

Along with this article, look at the Word to DITA Editors page on DitaUsers.org, which has links to four tools.

Labels: DITA, Microsoft Word, XML

Alan Houser is a well known DITA and XML expert. I took an XSLT course from him at Front Runner last year, and he definitely knows his stuff. He now has a blog. This is another one I'll be adding to my Bloglines subscriptions.

Labels: DITA

While DITA holds a lot of promise, implementing it takes knowledge in areas other than just technical writing - you'll need to know a bit of XML and some XSLT. Large writing groups or departments can afford to dedicate a person to handling the more technical side of things but it's harder for a single writer or small group. Lone-DITA is a site that "aims to help small documentation teams and small/medium organizations to evaluate and implement DITA. The main feature of the site is a comprehensive tutorial that will guide users through the all major stages necessary to create technical documents using DITA and the DITA Open Toolkit."

Labels: DITA

DITA World is a meta site containing links to other DITA sites and reference material. It's a handly quick reference if you're looking for information on DITA.

Labels: DITA

The DITA Open Toolkit User's Guide has been updated to cover version 1.3.1 of the DITA Open Toolkit. This version includes new sample files and quite a bit of updated content. If you're using the latest version of the toolkit, you'll definitely want this.

Labels: DITA

One of the things that makes DITA interesting to some people is its concept of specialization - a way of extending the base DITA elements to handle new types of information. However, it's not for the faint hearted. Elliot Kimber has put together a tutorial on DITA specialization, along with a blog post describing some of the issues he faced during its development.

It is of course written as a set of DITA topics, which is interesting in and of itself because a tutorial is a type of document for which the DITA concept/task/reference and highly fragmented presentation paradigms are not necessarily a good match. For example, I discovered that the only way to get prev/next links from one topic to the next within a logical narrative sequence of topics is to set their parent container in the organizing map to "sequence". However, this has the effect of numbering each topic in the sequence, which makes sense for the topics that represent a logical sequence of steps within the tutorial, but not for the purely conceptual overview of what DITA specialization is. (This is what the DITA Open Toolkit does today--whether this behavior is required by the DITA spec is a more subtle question.)

So it raises some issues, like do we need a tutorial-specific set of specializations and corresponding rendering customizations to get the effects I want as a tutorial author, or does the DITA spec need to be refined to reflect these sorts of more subtle rhetorical distinctions? Are my topics that describe a sequence of steps to be performed really task or concept topics (I've coded them as concepts because even in DITA 1.1, the task topic type is too restrictive in the way it represents sequences of steps)?

Labels: DITA, XML

While DITA has many benefits for authors of technical documentation, it isn't the solution for everything. Help authoring is one area in which it falls short, at least according to a paper by Tony Self on the OASIS site (Note that it's Word file). He examines the feature set of many common help authoring tools and compares it to what you can do (or not do) in DITA, using the standard Toolkit output.

For example, you can't do popup topics, which is one limitation I've also discovered as I work on a conversion project. Other things, especially those using DHTML effects are either impossible or hard to do. He also proposes some enhancements or specializations to DITA that might make things easier for help authors.

This is a good piece of work and essential reading if your authoring plans include both DITA and online help.

Labels: DITA, technical communication

DITA architect Don Day has updated his list of requirements that you should be considering when looking for an XML editor to work with DITA.

If you are involved with evaluating editors and other DITA tools, try to have a realistic approach to what you are looking for. Recognize that many of these task-assistive features are only just now appearing on higher-end full XML editors. But you don't have to hold all editors up to these standards. For example, an emerging class of DITA editors are components that operate through Web browsers, meaning they must trade off full-featured generality for highly focused function in a small footprint.

As I offered back in 2005, ultimately you must make cost/benefit judgments on the features that mean most to your intended scenarios, business rules that need to be supported, and the willingness of your team to learn some new ways of doing things.

Labels: DITA, software, XML

Dita Storm is a free, online, DITA editor written in JavaScript. You can use it to create basic DITA topics and map files. It won't replace XMetal or strucutred FrameMaker, but it is free, and all you need is a current web browser.

I used it to create a simple task file and it did create valid XML, though it didn't add an XML declaration or namespace information. So you'd probably have to tweak the results in a full XML editor. Of course, I could have missed quite a lot in my brief foray into the editor. I did find that right-clicking on an element opens a properties dialog that allows you to add attributes.

Labels: DITA, software, XML

Most companies who are considering using structured authoring tools, such as DocBook or DITA, are also considering a content management system. DITA has some special requirements that should be considered, and W. Elliot Kimber examines these in a post on his Dr. Macros's XML Rants blog.

So I thought I would try to outline what I think the key DITA non-obvious content management features are that any CMS that claims to provide DITA support should provide. I will not state what should be obvious requirements related to the creation and management of links, the ability to search on content and metadata, and so on.

Labels: content management, DITA, XML

I watched (attended?) a Quadralay webinar yesterday in which they demoed their DITA adapter for WebWorks ePublisher Pro. You'll be able to use this to integrate DITA content into an ePublisher project, alongside content from FrameMaker and Word. It'll be an extra cost purchase though, as it'll be sold separately from the Word and FrameMaker versions. Release is scheduled for sometime this quarter.

This will give you a lot more control over the output of your DITA projects than you can get through the DITA Open Toolkit. You'll still need another option for PDF output, as in the first release, the adapter won't output to PDF. It does look like a good choice for organizations that are still moving to DITA, and need to integrate structured and unstructued content.

Labels: DITA, software, XML

The ditamap.com site has put up a page collecting links to presentations about DITA from many different sites. Currently, there are about 30 listed and I'm sure more will be added. You can search the presentations or browse by event - for example, there are already 6 presentations from DITA 2007. This should be a useful site for anyone interested in DITA.

Labels: DITA, technical communication

Here's another addition to the long list of new, web-based applications: DITA Storm, a DITA XML editor. Currently, it doesn't support the whole set of DITA tags, but the most common ones are represented. Editing is similar to XMetal or structured FrameMaker, with tags and text, not code. Commerical licenses start at $199 for a 5-user license; free licenses for open source and non-commercial projects are available.

Labels: DITA, software, technical communication

The Content Management Strategies 2007 conference will be held in Boston this year from March 26 to 28. I attended last year's conference in San Francisco and thought it was excellent with a good mix of programming that covered content management and a strong DITA track. This year gives DITA even more emphasis as the conference is also billing itself as the "DITA North America 2007 Conference".

It doesn't look like I'm going to be able to go this year, unfortunately. Hopefully the pogramming notes will be available online after the conference. If you're looking for something to spend your travel/conference budget on (if you're lucky enough to have one), I'd recommend this conference highly.

Labels: DITA, technical communication

Here's an article by Scott Abel of The Content Wrangler blog reviewing significant trends in technical communication during 2006. Not surprisingly, the increasing acceptance of DITA is the most significant trend.

This year, no other technology had as wide an impact on the technical communication industry as the Darwin Information Typing Architecture (DITA). Supported by software vendors small and large and adopted as a technical documentation standard by the Organization for the Advancement of Structured Information Standards (OASIS), DITA, at its most basic level, is a document-creation and management specification that builds content reuse into the authoring process. It's also a shortcut to XML authoring, eliminating the need for organizations to create their own XML publishing paradigm from scratch.

Labels: DITA, technical communication

The Silicon Valley DITA Interest Group has archived presentations from their monthly meeting. The September presentation on information architecture is particularly interesting.

Labels: DITA

I watched a webinar the other day on the new features of XMetal 5.0. The editor features tighter integration with DITA (assuming you buy the DITA module, better intergration with content management systems, a reviewing moduule, and other useful features. The archived webinar is available for viewing on the Webex site. I'm putting XMetal on my short list of tools to look at for next year.

Labels: DITA, XML

I've posted quite a bit about DITA (Darwin Information Typing Architecture), because I think it's going to be one of the major forces in technical communication during the next few years. If you want a good introduction to DITA, you could do a lot worse than Scott Nesbitt's article, An Introduction to DITA. If you're already familiar with DITA, this would be a good one to pass to your boss when you ask for the new XMetal 5.0.

Labels: DITA