Structured Authoring

The site is about Structured Authoring. That is a broad subject, but will focus on SGML and XML and the implementation. Tools used to author, manage, communicate and deploy data usually in the maintenance from some small widget to a large weapon system. Covering Mil-Stds and S1000D.

Wade, Douglas Paul. Structured Authoring (2009). Resources>Documentation>XML>Blogs

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

Endless Possibilities: Norm Walsh on the Changing Nature of Publishing

Why XML documents aren’t a good fit for relational databases, how university professors are creating custom text books for students, and find links to several innovative projects that are demonstrating the power of XML and its cousin XQuery.

Walsh, Norman and Scott Abel. Content Wrangler, The (2009). Articles>Interviews>Information Design>XML

Linking and Relationship Tables  

Inline links and citations can be disruptive to the flow of information. Try to delete them because a topic is a discrete unit of information that is meaningful when it is displayed alone.

Henry, Carolyn. Silicon Valley DITA User's Group (2005). Articles>Information Design>XML>DITA

DITA Linking and Relationship Tables

Overview of best practices for using ditamaps and relationship tables to manage linking.

Stark, Scott. DITA Users (2007). Articles>Information Design>XML>DITA

Improving Relationships in Relationship Tables

While topic relationships can be stored in the topics themselves, as products evolve and user interfaces change, a topic that was required for release 1.0 of a product may no longer be needed in release 2.3. If related topics are maintained at the topic level, removing a topic that is no longer part of the system may involve modifying the related topics of a dozen different DITA files.

Binder, Zachary. XML.org (2008). Articles>Information Design>XML>DITA

DITA Keyref Example: Links from Glossary Entries

Because keyref is so important and because it also has inherent, unavoidable complexity, I will be posting short examples of how keyref can be used to solve specific business problems. This is the first in an occasional series of such examples. This example shows one particular application of the keyref feature to a real-world problem faced by one of Really Strategies' clients.

Really Strategies Blog (2009). Articles>Information Design>XML>DITA

Developing DITA Maps  

DITA maps provide a mechanism for ordering topics and creating a topic hierarchy. Because DITA maps consist of lists of references to topics, you can reorganize the content in a deliverable simply by changing the order of the topic references. You can create different maps referencing the same source topics to create two deliverables to meet different users' needs.

Linton, Jen. ComTech Services (2006). Presentations>Information Design>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

XML and Marketing Materials

Marketing materials are always important, and in these difficult times, they are critical to the success of the organization, and there are huge pressures to do more with less and for less money. Enter XML. XML is often perceived as complex, rigid and horrible to work with (geeky, technical) — anathema to the average marketing communications author. But this is no longer true. XML and the tools that support them have matured to the point where the XML is hidden, much in the same way RTF is hidden from the average Microsoft® Word author. Using XML for marketing materials provides considerable benefits, including consistent messaging, reduced time to create content, reduced costs to maintain content, reduced translation costs, and powerful multichannel conversion capabilities. XML is creating a profound shift in the way we create, manage, deliver and control marketing materials. It is a shift that is resulting in significant ROI and increased levels of success.

Rockley, Ann. Rockley Group, The (2009). Articles>Content Management>Marketing>XML

Design Patterns for Information Architecture with DITA Map Domains

The Darwin Information Typing Architecture (DITA) provides maps for assembling topics into deliverables. By specializing the map elements, you can define a formal information architecture for your deliverables. This architecture provides guidance to authors on how to organize topics and lets processes recognize your organizing principles, resulting in a consistent, clear experience for your users.

Hennum, Erik, Don Day, John Hunt and Dave Schell. IBM (2005). Articles>Information Design>XML>DITA

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

Enabling Web Service with Common Information Model

In this article we will introduce the concept of WS-Management and Common Information Model (CIM). By exploring the SOAP message with multiple examples, we will learn how to transfer CIM operations through WS-Management SOAP messages.

Hao, Sun. IBM (2009). Articles>Web Design>Information Design>XML

Painless XML Authoring?: How DITA Simplifies XML

Structured writing requires an analysis of content and a reorganization into the smallest possible coherent topics.

Doyle, Bob. SlideShare (2007). Presentations>Content Management>XML>DITA

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

DITA For Business Documents? New OASIS Committee Says "Yes!"

Think DITA is just for procedural technical documents? Think again. A new OASIS DITA sub-committee has been announced whose purpose it is to explore using the popular technical documentation standard known as the Darwin Information Typing Architecture (DITA) outside technical documentation projects.

Content Wrangler, The (2007). Articles>Business Communication>XML>DITA

DITA Open Platform

The DITA Open Platform is a free, open-source project which goal is to provide an enterprise platform for the edition, management and processing of DITA documents.

DITA Open Platform. Resources>Information Design>XML>DITA

Easy Command Line Processing with the DITA Open Toolkit

The DITA Open Toolkit can transform your DITA files into a wide variety of output types. When you first install it, it's easy to get the impression that you need to know Ant well to use it, but you can pack most of its available options into a single Java™ command line.

DuCharme, Bob. IBM (2008). Articles>Content Management>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

XSLT Tutorial

XSL stands for EXtensible Stylesheet Language, and is a style sheet language for XML documents. XSLT stands for XSL Transformations. In this tutorial you will learn how to use XSLT to transform XML documents into other formats, like XHTML.

W3Schools (2007). Resources>Information Design>XML>XSL

Controlling Whitespace, Part 1

XML considers four characters to be whitespace: the carriage return, the linefeed, the tab, and the spacebar space. Microsoft operating systems put both a carriage return and a linefeed at the end of each line of a text file, and people usually refer to the combination as the "carriage return". XSLT stylesheet developers often get frustrated over the whitespace that shows up in their result documents -- sometimes there's more than they wanted, sometimes there's less, and sometimes it's in the wrong place. Over the next few columns, we'll discuss how XML and XSLT treat whitespace to gain a better understanding of what can happen, and we'll look at some techniques for controlling how an XSLT processor adds whitespace to the result document.

DuCharme, Bob. XML.com (2001). Articles>Information Design>XML>XSL

Automating Stylesheet Creation

Since the early days of XSLT, many have asked whether it was possible to automate the creation of XSLT stylesheets. The general idea of filling out a form or dragging some icons around, then clicking a button and seeing a productive stylesheet generated from your input has always appealed to people. However, the problem of generating working XSLT syntax from the result of someone clicking on pull-down menus and radio buttons has not attracted many takers.

DuCharme, Bob. XML.com (2005). Articles>Information Design>XML>XSL

Push, Pull, Next!

In a recent weblog post, XML.com's "Python and XML" columnist Uche Ogbuji provided a nice collection of links to discussions about the push vs. pull styles of XSLT stylesheet development. What do we mean by "push" and "pull"? As a short example of each, let's look at two approaches to converting the following DocBook document to XHTML.

DuCharme, Bob. XML.com (2005). Articles>Information Design>XML>XSL

Seeking Equality

XPath 1.0 (and hence your XSLT style sheets) considers two elements to be equal if their string values are the same. The string value is essentially all of the PCDATA between the element's start and end tags, even if the element has descendant elements. For example, an XSLT processor considers the w and z elements in the following to be equal, because they both have a string value of "abcdefghi".

DuCharme, Bob. XML.com (2005). Articles>Information Design>XML>XSL

The Path of Control

Covers XPath's new ability to do some things that every real programming language can do: conditional statements and iteration, or, as they're more colloquially known, "if" statements and "for" loops. We'll also look at a useful related technique for checking whether certain conditions do or don't exist in a set of nodes.

DuCharme, Bob. XML.com (2005). Articles>Information Design>XML>XSL