Many organizations are bogged down in tedious, repetitive tasks — especially when it comes to documentation. The solution is to automate! Automation improves efficiency, saves time, eliminates redundant operations, and reduces costly errors. Any time your people are thinking, “there must be a better way,” there probably is!
RuDi – A Ruby-based System for DITA document generation
RuDi stands for Ruby-based Utilities for DITA processing. The idea is create a build system for DITA projects that is easy to use, and the same time very powerful — something that is accomplished by using the Ruby language and Ruby-based tools. (The project was originally hosted at
Kenai. Until it finds a new home the project code is contained in the RuDi zip file.)
Decision Guide Specialization
Figuring out which components you need and accessing the documents that describe them is a big issue for any reasonably complex system. Providing an end-user with the ability to do that is a huge part of “usability” in documentation. One of DITA’s most important advantages is the ability to define specialized document structures. That capability can be used to define a Decision Guide document type.
Transcluding the Invariants
Having settled on a strategy of composition, the next question is whether to transclude the parts of the text that change from version to version (the variants) or whether to transclude the invariants, instead—the boilerplate and other things that don’t change. This article lists the advantages of the latter course of action.
Conditionals vs. Composition
This article is part of a series that describes the 20-some decisions that face every DITA project. The goal is to identify the pros and cons for each decision and, where warranted, record the known “best practices” around each decision point. (Most of them can be covered in a single article. But a couple, like this one, are intricate enough to require an article of their own.) The series concludes by considering whether DITA would benefit from the creation of a specialization for a “
Decision Guide“.
The 20+ DITA Project Decisions
A list of choices that a DITA project needs to consider.
DITA 101 – Introduction
These slides are for a talk that introduces the fundamental concepts of the DITA documentation model.
DITA 101 – Training
These slides are for a longer series of presentations that tell people how DITA works.
A “Just In Time” Information System
This article describes the concept for the Pangaea Project. The goal of that project is to define (and build a reference implementation for) a human-mediated knowledge base that provides “just in time” information — information when you need it.
IBIS as a Design Methodology
This article is based on a Jan 2006 post to Blue Oxen Collaboratories mailing list. For some excellent follow-up discussion, visit that link. As I wrote then, “The ontology guys are going to love this one.” (Because this article presents an ontology for design discussions carried on using a structuring language based on Horst Rittel’s IBIS methodology, or “Information-Based Information System” (via Jeff Conklin).
(#)