Wednesday Oct 22, 2008

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. (Reports filed by users are an exception, but only if that is the only means they have to provide feedback.)

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.

[Read More]

Monday Jan 14, 2008

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]

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

JRuby: What I Need to Know

I was recently asked, "As a developer, what kind of stuff do you need to know--what kind of information do you need to learn the language and be productive in it?" Here are the thoughts that come to mind in response to that question.

[Read More]

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]

Monday Aug 13, 2007

Online Document Collaboration

We could collaborate online to edit structured documentation formats
like DITA. How cool would that be? And what problems do we need to
solve to make it happen? 

[Read More]

DITA, XDocs, and Online Collaboration with the Open Source Community

What I've been doing lately: The DITA format, the XDocs CMS, and online document collaboration systems.

[Read More]

Wednesday Jul 18, 2007

Enabling Collaborative Design-and-Decision Discussions, Online

We can enable online, collaborative discussions, and do a better job of tracking the designs and decisions they reach.

[Read More]

Thursday Jul 12, 2007

Doing DITA Builds Better

Enabling incremental builds for DITA...

[Read More]

« June 2016