Sunday Apr 13, 2008

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]

Saturday Mar 01, 2008

DITA Production Maps -- A Proposal

The DITA topic hierarchy that goes into a production system invariably does not match the desired hierarchy of documents coming out of it. And in any mixed-document system where not all docs are in the DITA format, it is invariably the case that xrefs to external documents need to resolve to different locations when documents are published in different contexts. They may require absolute links in some contexts, but be able to use relative links in others--but the relative location may change, depending on context.

This post contains a proposal for production maps. The goal is to control link generation at production time, automatically insert xrefs at authoring time, and automate link management in Content Management Systems when document names and locations change.

Since it touches the DITA standard itself, and all aspects of the tools ecosystem that surrounds that standard, any attempt at implementation will require a significant amount of time. (In the process, the proposal will undoubtedly undergo significant modification, as well.) But at this point, I don't see any alternative that will successfully divorce the output hierarchy--and link resolution--from the input hierarchy.

[Read More]

Monday Feb 11, 2008

Structured Document Formats, Part II

After writing, Are Structured Docs Really Necessary?, I was asked:
> Having written up that interesting discussion, what is your gut feeling at this time?
> If you had to make an authoring recommendation to a group to make life easier
> going forward, what would it be?
Well, I found myself going back and forth, as you can tell. That post reflected two weeks of thoughts that kept surfacing after a particularly stimulating discussion. This post is an attempt to come up with an answer.[Read More]

Saturday Feb 09, 2008

Do We Really Need Structured Document Formats? (Is Real Reuse Possible?)

Do we really need structured document formats? In one meeting, every reason we came up with that made them seem necessary, was answered by a convincing counter argument. "Reuse" would seem to be the most important reason. And maybe there are some compelling cases. But  maybe all-out reuse isn't needed. Maybe we really only need a very restricted form that solves those cases.

This post summarizes the arguments we considered. Do they demolish the case for structured documents and reuse in a highly fluid setting like the software industry? Are they wrong in some important respect? Or do they overlook some vitally important point that makes structured document formats irreplacable?

You be the judge. And please let us know. We really want to know.[Read More]

Tuesday Jan 29, 2008


Surprisingly, BlogRoller does not seem to have an archive of past posts. The posts have permalinks, so bookmarks can still find them, and they can be found by searching, but there is no way to browse old posts, once they age out of the system. This index page rectifies that situation until it changes or until I find a Wiki I really like, in which case I'll maintain the index there.[Read More]

Tuesday Jan 22, 2008

Wish List for Open Source Docs

My feature wish list for a system that would make it possible to easily interact with the open source community.[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]

Monday Jan 14, 2008

Sunbird -- One Cool Calendar

It's a wicked-nice calendar. There are a couple of wishlist items, but basically, this is it.[Read More]

Towards a Coherent Voting Advice System

Get the voting advice you need, when you need it, all in one place! The parts are all in place. We just need to bring them together.[Read More]

PermaLinks, Purple Numbers, and the Semantic Web

HTML's "id" attribute works better than named anchors for "Plain Old Semantic HTML" (POSH) web pages, especially for self-referential "purple links", which had their origins in Doug Engelbart's 1968 demo!
[Read More]

Wednesday Dec 19, 2007

My Windows XP Adventure

The need to rebuilding my Windows XP system turns into an adventure after running out of disk space and deleting one too many things to make room.[Read More]

Sunday Dec 09, 2007

Fuzzy Authorship: A Mechanism to Motivate and Reward Collaboration

There is nothing quite as rewarding as seeing in your name in lights for doing something good. Getting recognition for your work is one of the big motivators for social beings such as ourselves. Attribution is therefore an essential part of the publishing process--especially for collaborative documents like Wiki pages. But how is authorship to be determined? Having to click different buttons for major and minor changes just complicates things. Better if we can automate the process. This process suggests some "fuzzy logic" heuristics we can use.
[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]

Tuesday Oct 02, 2007

Build-to-Order Docs--Today!

Not long ago, I blogged on the subject of build-to-order documentation. A few weeks later, along comes a system that is doing it. Today! It doesn't work in exactly the way I envisioned, but it's working and available, with no waiting. Now I know how hard it is to be a science fiction writer. You write about the most far-fetched thing you can think of, and the next week someone's announcing it.[Read More]

Monday Sep 17, 2007

Using Java Classes in JRuby

I recently had occasion to write a JRuby script that used Java APIs in the XDocs CMS. I found most of the information I needed scattered around the web (the URLs are listed in the Resources section at the end). I decided to collect the relevant stuff in one place, leaving out the stuff that seemed extraneous, and adding the additional little bits that turned out to be necessary. This post contains the results. (But things may well change, so let me know if there are errors or it needs to be brought up to date!)[Read More]

« April 2014