An XML Architecture for Technical Documentation: The Darwin Information Typing Architecture

DITA is an architecture for creating topic-oriented, information-typed content that can be reused and single-sourced in a variety of ways. It is also an architecture for creating new information types and describing new information domains, allowing groups to create very specific, targeted document type definitions using a process called specialization, while at the same time reusing common output transforms and design rules. We discuss several methods that can be used to extend DITA's basic topic types.

Day, Don, Erik Hennum, John Hunt, Michael Priestley, David Schell and Nancy Harrison. WritersUA (2004). Articles>Documentation>XML>DITA

XML Documentation: The Missing Link (1)

Technical documentation is a prime beneficiary of XML technology, with standards such as DocBook and DITA. However, while XML revolutionized the way technical documentation is written, it did nothing to help documentation teams improve the collaboration process with the SMEs and other invested parties. In some cases, things got worse, with another layer of complexity added between the documentation team and the documentation stakeholders. Where is the missing link?

Talbot, Fabrice. LiveTechDocs (2008). Articles>Documentation>Software>XML

XML Documentation: The Missing Link (2)

Sharing XML documents during the writing and review process is a missing link in the XML publication chain. While Office or PDF applications help, they also add another extra-layer of complexity and lose the 'XML awareness' of our initial document. That's where LiveTechDocs comes into play.

Talbot, Fabrice. LiveTechDocs (2008). Articles>Documentation>Software>XML

XML Editors for Technical Documentation

Looking through my Programs folder, I see many programs I use to work with XML documentation. Which one is my favorite? Well, that depends on the size of my project, the size of my budget, and the file I am working on.

Mulvihill, Teresa. LiveTechDocs (2008). Articles>Documentation>Software>XML

XML Schema Tutorial

In our Schema tutorial, you will learn what an XML Schema is, how XML Schema will replace DTD, and how to use the XML Schema language in your applications.

W3Schools. Articles>Documentation>Tutorials>XML

XML-Based Documentation Using AurigaDoc

A review of an XML-based documentation tool.

Nesbitt, Scott. NewsForge. Articles>Documentation>Software>XML

XML: the Future of Windows Help?

For a long time we've been told that XML Help is the future. So is it? In this article, David Rose examines the current state of the online help development industry and the direction it is heading.

Rose, David. Armada Online (2005). Articles>Documentation>Help>XML

The Steepest Part of the Learning Curve is Right at the Start

Microsoft has a lot of information on their sites about these products. Unfortunately, I can never find it. I usually only know it’s there when I stumble on it months after I really needed to know it. The steepest part of the learning curve is at the start. Likewise with another program I use occasionally—DITA. DITA is an xml schema used for writing documentation.

Technical Writer (2008). Articles>Documentation>XML>DITA

The Hidden Cost of DITA

In the past few years, we have implemented both DITA-based and custom XML solutions for our customers. Given the right set of circumstances, DITA provides an excellent foundation for structured content. But I seem to be in significant disagreement with DITA advocates about how often the "right set of circumstances" is present.

O'Keefe, Sarah S. Carolina Communique (2008). Articles>Documentation>XML>DITA

DITA Metrics - Cost Metrics

You’ve read all the papers on ROI for XML and you get it. You’ve already concluded that moving to DITA will save you tons of time and money. But management says prove it. This paper helps you determine the cost portion of the ROI calculation. What are my costs now? What will my new costs be with DITA? And what is the difference—my savings? This white paper is the first in the DITA Metrics series. The series will discuss cost metrics, reuse metrics, and a reuse strategy. This paper describes one model for calculating the cost of a DITA project. After doing some content analysis on your own documentation, you can customize this cost model to suit your documentation project. In the end, you should be able to speak the financial language of managers and prove to them in dollar signs the value of moving to DITA.

Lewis, Mark A. Content Wrangler, The (2008). Articles>Documentation>XML>DITA

Using DITA XML for Instructional Documentation  

Why DITA XML? Open standard and built-in with OpenTopic. Very specific schema. Helps clarify documentation.

Thomas, Andrew. Adobe (2005). Articles>Documentation>XML>DITA

An XML Architecture for Technical Documentation: The Darwin Information Typing Architecture (DITA)

DITA is an architecture for creating topic-oriented, information-typed content that can be reused and single-sourced in a variety of ways. It is also an architecture for creating new information types and describing new information domains, allowing groups to create very specific, targeted document type definitions using a process called specialization, while at the same time reusing common output transforms and design rules. We discuss several methods that can be used to extend DITA's basic topic types.

Day, Don, Erik Hennum, John Hunt, Michael Priestley, David Schell and Nancy Harrison. WritersUA (2004). Articles>Documentation>XML>DITA

Why the Future of Documentation Belongs to Extended Markup Language?

XML, that is, Extended Markup Language, is the future of technical writing. There are TWO important reasons why that is so: XML is at the heart of “single sourcing” movement; and XML is a documentation manager’s dream since writing once and publishing many times drops unit production costs tremendously.

Akinci, Ugur. Technical Communication Center (2009). Articles>Documentation>XML>Planning

Structured Authoring for Everyone

While the concepts of structured authoring are more than just slightly useful for technical writing, they can be beneficial for just about any writing task within an organization. But how do you bring XML-based structured authoring to the masses? Perhaps by taking a cue from a word processor called Yeah Write.

Nesbitt, Scott. DMN Communications (2009). Articles>Documentation>XML>Technical Writing

Extensible Schema Documentation with XSLT 2.0  

XML Schema documents are defined using an XML syntax, which means that the idea of generating schema documentation through standard XML technologies is intriguing. We present X2Doc, a framework for generating schema-documentation solely through XSLT. The framework uses SCX, an XML syntax for XML Schema components, as intermediate format and produces XML-based output formats. Using a modular set of XSLT stylesheets, X2Doc is highly configurable and carefully crafted towards extensibility. This proves especially useful for composite schemas, where additional schema information like Schematron rules are embedded into XML Schemas.

Michel, Felix and Erik Wilde. WWW 2007 (2007). Articles>Documentation>XML>XSL

Using DITA for Publishing Documentation in Eclipse Help Format

This article discusses main challenges that documentation team faces when it decides to use DITA as a source format for Eclipse Help documentation. It also explains how DITAworks documentation tool plans to address these challenges.

DITAworks (2009). Articles>Documentation>XML>DITA

DITA Open Toolkit Customization

This paper outlines a course given by Adena Frazier of Suite Solutions--a course which is highly recommended for anyone who wants to get the most of the OT. This paper outlines the most important processes, but it leaves out many of the details, tips, and debugging notes that were included in the course. Note, too, that errors easily could have crept in, and some details are bound to change for later versions of the toolkit. (We used version 1.4.1) So it makes a lot of sense to take the course, even if you find the outline useful.

Sun Microsystems (2008). Articles>Documentation>XML>DITA

What a Technical Writer Should Know About DocBook?

DocBook is a set of tools for implementing XML (Extended Markup Language)-based structured documentation. It is developed back in 1991 and is widely used today by those technical writers who generate single-sourced documentation. It is especially well suited for software, hardware and networking documentation.

Technical Communication Center (2009). Articles>Documentation>XML>DocBook

Producing Documentation and Reusing Information in XML, Part 3: Creating Multi-Target XML Documents

XML is an optimal format for writing documentation that you can use with many different documentation software packages and production environments. In this third article in the series, discover how to create single-source documents that can produce output in a variety of different output formats.

von Hagen, William. IBM (2009). Articles>Documentation>XML>DocBook

Ten DITA Lessons Learned from Tech Writers in the Trenches

This top ten list is based on interviews conducted by TheContentWrangler.com with technical writers at more than 20 software companies—tech writers that are actually using DITA to create documentation today.

Content Wrangler, The (2006). Articles>Documentation>XML>DITA

Authoring with Eclipse

The topic of technical publishing is relatively new to the world of Eclipse. One can make the argument that technical publishing is just another collaborative development process involving several people with different backgrounds and skills. This article will show that the Eclipse platform is a viable platform for technical publishing by discussing how to write documents such as an article or a book within Eclipse. In fact, this article was written using Eclipse.

Aniszczyk, Chris and Lawrence Mandel. Eclipse (2005). Articles>Content Management>Documentation>XML

Use Cases for User Assistance Writers

Perhaps the true measure of a good idea is its persistence, even though folks are slow to pick up on it. SGML is a good example. It seemed like a great idea, but for a long time, had trouble getting traction in the general tool space. Then it started showing up at technical communication conferences wearing a name badge that said, “Hi, my name is DITA,” and suddenly, it’s a hit!

Hughes, Michael A. UXmatters (2009). Articles>Documentation>XML>DITA