A directory of resources inthe field of technical communication.

Armstrong, Eric

10 found.

About this Site | Advanced Search | Localization | Site Maps



Build-to-Order Documents with DITA

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.

Armstrong, Eric. Sun Microsystems (2007). Articles>Documentation>XML>DITA


Building a Bridge: DITA, DocBook, and ODF

Some folks here are taking a very strong look at DITA. I'm certainly one of them. But we also have a huge legacy of documents in Solbook format (Sun's subset of DocBook). There are tools for editing such documents, and tools for processing them. and there are many people who are comfortable with those tools. So DITA isn't going to replace the world, just yet. But DITA makes extensive reuse possible. It's a format with a serious future, because "reuse" is a very big deal. It lets you single-source your information content so have one place to make an edit. That sort of thing becomes important when you have multiple revisions of a product, and/or multiple variations. It becomes important when different tools and different products use the same information in different ways. It can drastically improve quality, ensure uniformity of presentation. Finally, structured formats like DITA and DocBook create the kind of consistently-tagged information that allows for useful automation.

Armstrong, Eric. Sun Microsystems (2007). Articles>Information Design>XML>DITA


Creating Topics: Where do you Draw the Line?

It's hard to look at a page of text and try to decide where to divide things to create individual topics. That "bottom up" approach is kind of pointless, in fact. There are better ways.

Armstrong, Eric. Sun Microsystems (2008). Articles>Documentation>Information Design>Technical Writing


Daisy: WYSIWYG Wiki for PDF Books   (PDF)

If you need the collaborative aspects of a Wiki combined with DITA's modular topics and publishing capabilities, then DAISY might just be the system you need--and it's free. DAISY provides WYSIWYG editing for Wiki pages that can be combined to publish books, either in a PDF or as a single HTML page.

Armstrong, Eric. Sun Microsystems (2008). Articles>Content Management>Documentation>Wikis


Docs Aren't Code

In the world of development, the need to track bug reports and enhancement requests are a given. But they're not generally required for documentation, in the way they are for code Quite the reverse. For documentation, bug reports and enhancement requests provide little benefit, and generally impede progress. This post compares documentation and code, showing why bug reports and enhancement requests are so vital to the code base, and at the same time why those reasons simply do not apply to documentation.

Armstrong, Eric. Sun Microsystems (2008). Articles>Documentation>Programming>Technical Writing


Enabling Collaborative Design-and-Decision Discussions, Online

What if it were possible to manage the tendency of discussions to branch ad infinitum? What if it were possible to use those discussions to surface the important issues, identify the alternatives, make reasonable choices and, above all, provide a readable history of discussion that made it easy for someone coming along later to understand the basic architecture and find out why things are the way the are? There is an interesting coalition of technologies that could provide those very benefits.

Armstrong, Eric. Sun Microsystems (2008). Articles>Collaboration>Online


Modular Docs Part 1: Why You Want Modular, Topic-Oriented Documentation

When documents are built from components, and the components can have contextual variations, it becomes possible to construct built-to-order documents "on the fly", in response to user demands, rather than having to pre-create static versions of all possible variations. Once such a system is in place, it becomes possible for users to further customize the results by modifying the list of selected topics, rearranging their order, or even by adding new topics.

Armstrong, Eric. Sun Microsystems (2008). Articles>Documentation>Information Design


Modular Docs Part 2: DITA vs. DocBook

When IBM decided to focus on topic-oriented documentation, it created the Darwin Information Typing Architecture (DITA), even though there was already a huge investment in DocBook. Moving to a new architecture was a decidedly non-trivial undertaking--both technically and politically--so it is worth an inquiry as to the reasons for making that move.

Armstrong, Eric. Sun Microsystems (2008). Articles>Documentation>DocBook>DITA


The Value of Semantic Tags

So what's wrong with using <b>, <i>, and <tt>, anyway? What's so useful about identifying things as menu items, APIs, or filenames? Here's the list of reasons that surfaced at the recent 2008 DITA/CMS Conference. What are your thoughts?

Armstrong, Eric. Sun Microsystems (2008). Articles>Web Design>Content Management>Semantic


Wikis, Docs, and the Reuse Proposition

The Darwin Informaton Typing Architecture (DITA) is an XML-based document format that was designed from the ground up for reuse. It rocks. Content Managment Systms (CMSes) are designed to hold XML data. So in theory, a CMS system that lets you edit like a Wiki would be everything you need. But getting a system like that to work is a pretty tricky proposition.

Armstrong, Eric. Sun Microsystems (2007). Articles>Content Management>XML>DITA

Follow us on: TwitterFacebookRSSPost about us on: TwitterFacebookDeliciousRSSStumbleUpon