Thursday Dec 04, 2008

Information Architecture and Planning

JoAnn Hackos' course on "Minimalism" (user-centric, task-focused documentation) had useful guidelines for information architecture design. That topic-tracking tables she showed us became the foundation for the approach I now use. They made it possible to organize my work and keep track of what I was doing.[Read More]

Wednesday Dec 03, 2008

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.

[Read More]

Tuesday Oct 14, 2008

DITA OT 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.[Read More]

Monday Oct 06, 2008

Modular Docs Part 2: DITA vs. DocBook

This is the second in a two-part series. Part 1 describes the motivations for modular documentation. Part 2 zeros in on the reasons for choosing DITA.

[Read More]

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

This is the first in a two-part series. Part 1 describes the motivations for modular documentation. Part 2 zeros in on the reasons for choosing DITA.

[Read More]

Tuesday Jul 01, 2008

My Apache WebDAV/Windows Nightmare

Subversion is WebDAV-ready. Cool! "Just enable WebDAV in Apache". Riiigght... Like it was really that simple! But even after you get it working, there are problems: DreamWeaver's synchronization mechanisms leave a lot to be desired, and XMetaL access depends on mapping a drive in Windows--a mechanism that simply doesn't work--unless you manage to get SSL working in your WebDAV server, so you can make an https connection (something I never managed to do in Apache).


  • Initial Installation
  • Access Path Issues
  • Browsing Issues
  • DreamWeaver's Synchronization Model
  • XMetaL's Dependency on Windows
  • Conclusion

[Read More]

Sunday Apr 13, 2008

Daisy: WYSIWYG Wiki for PDF Books

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.


[Read More]

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, , or filenames? Here's the list of reasons that surfaced at the recent 2008 DITA/CMS Conference. What are your thoughts? [Read More]

SVDIG Notes: AirHelp and DITA File Names

Notes from the March meeting of the Silicon Valley DITA Interest Group, covering AirHelp and DITA naming conventions.[Read More]

Monday Jan 21, 2008

Domain Specific "PowerTool" Languages Promote Elegance

In both Ruby and DITA, domain specific languages make elegance possible. More importantly, each is producing an ecosystem of domain specific languages (aka "power tools") that is making it possible to do ever more as time goes on.[Read More]

Sunday Nov 04, 2007

Wikis, Docs, and the Reuse Proposition

Wiki systems make it easy to edit documents online. That makes them terrific for document collaboration. But current Wiki formats don't allow the kind of reuse that the DITA document format was designed for. But it may be possible to implement some of DITA's best features using a clever combination of JavaScript, CSS, and an extensible Wiki. I suspect it can be done most easily using a Ruby-based Wiki like MediaCloth.[Read More]

Friday Sep 14, 2007

Building a Bridge: DITA, DocBook, and ODF

We can make documents in one format appear as though they were authored in a different format, maintain single-sourcing, and do it all in a way that is transparent to the user. [Read More]

Wednesday Sep 05, 2007

Automated Code-Inclusions in DITA

When I was writing in HTML, I had a system that could easily transform a body of code into a sequence of versions that let the user experiment with the program and see how it works at each stage of the process. As a further benefit, it also produce HTML showing added code in bold and deleted code in strikethrough font. The big advantage was the ability to changed code in early versions in ways that made later versions easier (or possible). I could then re-generate all of the intermediate versions before doing the final writeup. That system saved a lot of work, but I still had to cut and paste the code fragments. Using DITA, I won't even have to do that--I can simply transclude the code fragment right into the document.
[Read More]

Friday Aug 31, 2007

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.

[Read More]

Wednesday Aug 15, 2007

Using JRuby for DITA builds

There are serious advantages to using JRuby for DITA builds. I first wrote about the idea in Doing DITA Builds Better.
That post mentioned Rake's advantage for sophisticated dependency
detection, but didn't say much about how to achieve that goal. This one outlines a development progression. In the process, it hopefully
elucidates the kinds of benefits that can be achieved.

[Read More]

« June 2016