Cool Stuff: What's New, What's Cool

I'm still a fan of the functionality that Daisy has implemented. But after having played with it for a bit, it seems to be somewhat less than optimal with respect to error handling and documentation.[Read More]

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]

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]

The 2008 DITA CMS Conference was informative, educational, and in many cases surprising.  My personal highlights include Daisy, DITAStorm, WebWorks ePublisher, and more...

[Read More]

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

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]