http://tc.eserver.org/dir/Articles/Documentation/XML A listing of the most recently indexed works about Articles and Documentation and XML in the field of technical communication. en-us Copyright (c) 2005-08 by the EServer. All rights reserved. tclib-editorial@eserver.org (TC Library Editorial Board) webmaster@eserver.org (Geoffrey Sauer) http://tc.eserver.org/images/newlogo.gif http://tc.eserver.org/dir/Articles/Documentation/XML http://tc.eserver.org/35225.html http://tc.eserver.org/35225.html 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! http://tc.eserver.org/35043.html http://tc.eserver.org/35043.html 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. http://tc.eserver.org/35047.html http://tc.eserver.org/35047.html 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. http://tc.eserver.org/35019.html http://tc.eserver.org/35019.html 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. http://tc.eserver.org/34784.html http://tc.eserver.org/34784.html 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. http://tc.eserver.org/34491.html http://tc.eserver.org/34491.html 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. http://tc.eserver.org/34273.html http://tc.eserver.org/34273.html 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. http://tc.eserver.org/34244.html http://tc.eserver.org/34244.html 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. http://tc.eserver.org/34070.html http://tc.eserver.org/34070.html 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. http://tc.eserver.org/34036.html http://tc.eserver.org/34036.html 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. http://tc.eserver.org/33729.html http://tc.eserver.org/33729.html Why DITA XML? Open standard and built-in with OpenTopic. Very specific schema. Helps clarify documentation. http://tc.eserver.org/33730.html http://tc.eserver.org/33730.html 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. http://tc.eserver.org/33183.html http://tc.eserver.org/33183.html 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. http://tc.eserver.org/32227.html http://tc.eserver.org/32227.html 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. http://tc.eserver.org/32083.html http://tc.eserver.org/32083.html 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. http://tc.eserver.org/31161.html http://tc.eserver.org/31161.html Having new DocBook standards in place may do little to push adoption. An important factor in driving user adoption is the availability of software that implements the standard. It would be interesting to see whether big software companies would jump on the bandwagon...Unless the open-source community comes to the rescue! http://tc.eserver.org/31167.html http://tc.eserver.org/31167.html When it comes to documentation projects, primarily technical, medical, and scientific, using XML is a no-brainer. The heavy thinking comes when deciding which flavor of XML to use: DocBook or DITA (Darwin Information Typing Architecture). I have been a steadfast supporter of DocBook for over six years. I'd tried my hand at DITA and gave it up as a fad; lots of bells and whistles, but too complicated to integrate. And couldn't DocBook do everything DITA promised anyway? http://tc.eserver.org/31165.html http://tc.eserver.org/31165.html 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? http://tc.eserver.org/31166.html http://tc.eserver.org/31166.html 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. http://tc.eserver.org/31164.html http://tc.eserver.org/31164.html 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. http://tc.eserver.org/31108.html http://tc.eserver.org/31108.html A blog post that presents a few thoughts on using technologies like DITA to author documentation. http://tc.eserver.org/30230.html http://tc.eserver.org/30230.html It is entirely possible to deliver custom, on-demand documentation that is precisely suited to a user's needs. It can be done today, using web-interface strategies and the right document format. This post shows how such a system could be implemented with the DITA format, and shows why it would be an ideal document-delivery system for programmers. http://tc.eserver.org/29971.html http://tc.eserver.org/29971.html Can DITA be used as a Help authoring technology? Superficially, of course it can! The DITA Open Toolkit includes an HTML Help transformer, an Eclipse Help transformer, and an HTML transformer (which can also generate some sort of Table of Contents). So isn't it obvious then? DITA is perfect for Help authoring. Or is it? Looking a bit deeper, it's not so obvious. Can I include context-hooks in my content? Can I specify a popup link? Can I build a modular Help system? If I can't, then DITA is probably not suitable for Help. http://tc.eserver.org/29972.html http://tc.eserver.org/29972.html Two of the oft-quoted benefits of DITA, the Darwin Information Typing Architecture, are 'single-sourcing' and 'content re-use'. These benefits do not only apply to the commonly-accepted definition of technical documents, but to many other forms of documents from outside the technical communicator's realm. http://tc.eserver.org/29635.html http://tc.eserver.org/29635.html By organizing information around the goals that users are trying to accomplish, you can provide task-based information that truly addresses user needs. This article walks through the steps for creating more useful information navigation by implementing information development best practices with examples in the Darwin Information Typing Architecture (DITA). http://tc.eserver.org/29342.html http://tc.eserver.org/29342.html XML-based development projects often require the development of a Document Type Definition (DTD), which defines the XML code used in an XML document or application. Even if you are customizing an existing DTD like the DocBook DTD, documenting the DTD is a best practice for a number of reasons, including:Providing documentation http://tc.eserver.org/29081.html http://tc.eserver.org/29081.html This article describes the influence that Extensible Markup Language (XML) will have on the software documentation process and subsequently on the curricula of advanced undergraduate and master's programs in technical communication. XML, an evolving set of standards for storing and displaying information, uses nine components that make up the XML development process. Grouped into content, formatting, and language specifications, these components enhance organizations' ability to manage information more efficiently and accurately. As the XML development process is adopted, the software documentation process will evolve from a self-contained procedure into a more flexible, interactive process in which software documenters must work closely with a wide range of specialists. The changes that XML will have on the software documentation process will likewise have implications for programs in technical communication in the need to address new kinds of job descriptions, skill sets, and career paths of future technical communicators. The article recommends adaptations to existing courses, as well as new elective and required courses. http://tc.eserver.org/28775.html http://tc.eserver.org/28775.html Having learned that two of these database companies already used single-source files for their error messages, BMC Software integrated the information about the error messages from the database companies. We accomplished our goal by negotiating with our partner companies for the source files of the error message information. This session discusses how we took those source files and modified them to create simple XML files, then transformed them into HTML using XSL transforms within a BMC Software product. http://tc.eserver.org/28263.html http://tc.eserver.org/28263.html Content reuse enables technical communicators to create multiple deliverables from a single set of source documents. A key component of reuse is identifying which information belongs in which deliverable. Some customization is feasible with build tags (RoboHelp), conditional text (FrameMaker), topic reuse (FrameMaker and AuthorIT), and similar features. http://tc.eserver.org/28230.html http://tc.eserver.org/28230.html Writing, compiling, and maintaining documentation is a necessary evil. While moving to DITA might not improve the quality of your documentation, it can streamline the process of creating and managing those documents. http://tc.eserver.org/28185.html http://tc.eserver.org/28185.html Implementing structured authoring with XML allows organizations to create better content. The addition of hierarchy and metadata to content improves reuse and content management. These benefits, however, must be weighed against the time and money required to implement a structured authoring approach. The business case is compelling for larger writing organizations; they will be the first to adopt structured authoring. Over time, improvements in available tools will reduce the cost of implementing structured authoring and make it affordable for smaller organizations. http://tc.eserver.org/28186.html http://tc.eserver.org/28186.html In a structured authoring environment, authors create documents by assembling elements and text in an order permitted by the structure definition document. You might think of structured authoring as being similar to template-based authoring with a strict template. Authors do not assign formatting; the formatting is automatically assigned based on the structure of the document. Formatting may differ for different output media. http://tc.eserver.org/28177.html http://tc.eserver.org/28177.html Not every content-creation group will benefit from structured authoring and XML. Sometimes, the expense of implementation outweighs the benefits realized, especially in smaller groups with less total page count. http://tc.eserver.org/27797.html http://tc.eserver.org/27797.html 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. http://tc.eserver.org/27740.html http://tc.eserver.org/27740.html Gets you started with DocBook, an SGML/XML dialect that describes the content of technical articles and other documents. David discusses the benefits of using DocBook, and then describes how to plan and modularize a large document conversion project. http://tc.eserver.org/27640.html http://tc.eserver.org/27640.html 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. http://tc.eserver.org/27076.html http://tc.eserver.org/27076.html Asks Puny Sen, Project Lead, Instructional Communications at Adobe Systems to talk about the software giant's foray into the world of the Darwin Information Typing Architecture (DITA). Sen shares details about Adobe's recent DITA documentation project, the pro's and con's of using DITA with FrameMaker, as well as lessons learned of importance to anyone interested in adopting the DITA standard. http://tc.eserver.org/27075.html http://tc.eserver.org/27075.html The purpose of this research note is to introduce the Darwin Information Typing Architecture (DITA) and highlight its relationship to other information architectures like DocBook and Information Mapping. http://tc.eserver.org/26373.html http://tc.eserver.org/26373.html This howto attempts to clear the fog and mystery surrounding the DocBook markup system and the tools that go with it. It is aimed at authors of technical documentation for open-source projects hosted on Linux, but should be useful for people composing other kinds on other Unixes as well. http://tc.eserver.org/26318.html http://tc.eserver.org/26318.html A review of an XML-based documentation tool. http://tc.eserver.org/26313.html http://tc.eserver.org/26313.html 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. http://tc.eserver.org/25444.html http://tc.eserver.org/25444.html This chapter is intended to provide a quick introduction to structured markup (SGML and XML). If you're already familiar with SGML or XML, you only need to skim this chapter. To work with DocBook, you need to understand a few basic concepts of structured editing in general, and DocBook, in particular. That's covered here. You also need some concrete experience with the way a DocBook document is structured. http://tc.eserver.org/25378.html http://tc.eserver.org/25378.html Creating an XML-based Content Management System to single-source technical publications is as simple as 1 - 2 - 3. OK, maybe it isn't quite that easy, but this article discusses how it can be done. http://tc.eserver.org/22621.html http://tc.eserver.org/22621.html Here are links to the listings described in <i>Managing and Documenting Your Project XML Style.</i> http://tc.eserver.org/21709.html http://tc.eserver.org/21709.html XML provides a robust, non-proprietary, and verifiable file format for the storage and transmission of text and data both on and off the Web. XML removes the complexity of SGML, making it easier to define your own document types, and to write programs to handle them. http://tc.eserver.org/21657.html http://tc.eserver.org/21657.html The issue of documenting schemas—or any machine readable language—goes beyond simple additions of comments. Thereal challengeistocreateschemasthat arereadablebothdirectlybylookingat their sourcecodeandbydocumentation extraction tools. http://tc.eserver.org/14781.html http://tc.eserver.org/14781.html In the cover article for Intercom's special issue on XML and HTML, Conlin discusses how the implementation of XML affects writers of documentation.