A recent comment by Yucheng on my preview of Dita4Hudson post finally motivated me to upload my starter code to SourceForge so that others can contribute and make use of it.

The plugin right now is mostly front-end code and does not yet run the DITA Open Toolkit transforms.  The intent of the plugin is to very simply provide text fields that a user can enter any and all applicable transform parameters for a given output type and then in the background those would be passed to the toolkit in the appropriate form and basically be a command line call.

I would love to see others pick up where I left off. I hope to be able to continue working on it again in the future, but for now I have too much else going on. I would be happy to help someone out with getting going with it. Please comment or use the contact form to get in touch.

• Dita4Hudson on SourceForge

I am progressing a bit further on my plugin that will allow for easier DITA builds within the Hudson continuous integration server.  Hudson is a quite handy build management system that offers you a lot of additional value on top of your existing builds and processes.

You can use your existing DITA-OT Ant scripts to build your output within Hudson. Many Dita users are not Ant experts and often Ant is one of the limiting factors in Dita adoption by smaller teams. I hope this plugin will help further promote DITA and provide another simple tool for Dita builds.

All feedback and suggestions are welcome.

Global properties configuration

Defining your DITA Open Toolkit installations. You can define multiple installations if it is ever necessary to use a back level version or for testing new versions prior to moving to production.

Adding a Dita build to a job

Jobs can include many steps and multiple builds. If you are building an Eclipse feature you might include your code build, context sensitive help build, and DITA transform to help topics within the same job.

I recently stumbled across the WinAnt Echidna project on SourceForge while browsing the DITA Open Toolkit project forums.  While DITA as a markup language is not difficult to learn and begin to start creating content, DITA can be difficult to see the fruits of those labors if you are just getting starting with the DITA-OT. Most information developers are not experts in XSL or ANT.  The WinAnt tool can help them get started with producing DITA sourced content very quickly.

WinAnt is generally going to appeal to writers and teams on smaller projects. Larger and more complex projects and deliverables likely have requirements that go beyond what WinAnt provides.

Benefits

• Free
• Quick to create and run both simple and customized builds
• Supports a variety of output types, including: XHTML, PDF, Eclipse plugin, HTML Help, JavaHelp, DocBook, and Word.
• Repeatable builds by saving build projects.
• Style settings can be controlled through skins, which list headers, footers, stylesheets and includes . Skins can be used for consistent settings amongst a team.
• Automation through scheduled tasks and saved build projects.
• Logs are styled and highlight messages produced by the build.
• ANT build.xml can be exported if your project needs to grow beyond what WinAnt provides.

Limitations

• Unclear about longevity and maintenance of the project
• Unable to customize or override XSL settings.
• Errors and warnings in build are not explicitly displayed. Must manually check logs for each transform. Expected a pop-up or dialog telling me that my project had X errors and Y warnings.
• Lack of support for specializations? (Unverified but looks that way from a quick attempt)
• Troubleshooting problems can be difficult.
• Runs on Microsoft Windows only.
• WinAnt help launches in odd sizes and is always on top of UI. No tooltips or descriptions for many settings.
• Lacks expanded tasks such as source code control extraction, distribution of output options, versioning of builds,  and advanced reporting.
• JavaHelp and HTML Help require additional installed programs that not distributed with program or linked from the UI.

When I first downloaded the product, I expected that I would be disappointed with it just based on my first impression. WinAnt for such a small and simple program is quite powerful.  I would suggest that anyone who is trying to get started learning DITA should definitely give this program a try. It definitely lowers the learning curve for DITA builds.

The WinAnt tool was created by Tony Self of HyperWrite. Nice work!

Wikis for documentation make sense for many reasons, including  low cost of implementation, ease of publishing, and collaboration possibilities.  DITA has become a popular XML format for semantic markup of information and is generally used for documentation.  Wiki content is generally authored or stored as wikitext, which is an non-standardized markup format.  Should DITA be used as a markup format for wikis instead of wikitext or HTML? I believe the answer is that DITA in the authoring environment of wikis is impractical and does not work for general audiences.

I work at IBM where DITA was first invented and where we author an unimagineable amount of content in DITA. We create all kinds of tools to support its authoring, transformation, translation, specialization, and delivery.  DITA has in various capacities been explored as a format for a variety of delivery mechanisms, including content management systems, wikis, microformatted XHTML that retains DITA markup, and also your more standard outputs.  Basically, if some tool or application is out there, we’ve likely tried to make it DITA friendly.

Know your audience

You must know your audience to create quality documentation that meets the requirements of the user.  Most of my users are database administrators and application developers. My guess is that none of the users of the products I work on knows a thing about DITA markup.  DITA requires some upfront education for anyone that is going to create content in the desired manner.

A core feature of a wiki is the collaborative editing and authoring aspect. By using DITA as the wiki markup, you are removing that feature by subjecting your potential authors to learning a new language and all its nuances. The word wiki in Hawaiin means quick. Quick also implies easy.

Subjecting one of our users to DITA authoring would be a significant hindrance in terms of their ease in offering contributions. Public collaboration on most documentation projects is extremely difficult.  Tom Johnson in his article on A Few Surprises in using a Wiki for Documentation discovered that most contributors were likely to only make small edits rather than add to the documentation set. Why throw another roadblock in the way?

Editing tools

Last time I checked, there were very few web-based DITA editors. The primary contenders were DitaStorm, XMetal XMAX, and Xopus.  I have tried both DitaStorm and Xopus for working with DITA. DitaStorm seems to be the more generally well known web-based tool of the bunch. I’ve tried it through its various versions and my general feeling is that for very basic authoring it works okay but for more specialized authoring and design it is unwieldy and often buggy. Within IBM, we had a few licenses for a project and I often found myself wishing I was just using Notepad instead for editing topics. The problems and challenges I experienced I feel were more due to Javascript issues especially around cursor placement, but as an experienced DITA user found myself very frustratred to not be able to easily get the output I desired.

Most people author their content visually to create the desired elements and effects. When they want emphasis on a term they will use bold or italics. They won’t want to consider should that emphasized text be a UIControl, parmname, apiname, varname, or one of the many other semantic tags–they will use the non-semantic bold tag.

Solutions?

Do you try to hide the complexity of authoring in DITA from users that do not care and just want to write? Do you create a kind of hybrid DITA wiki that features some of the benefits of both worlds? Is a light-weight CMS really a better solution for easy authoring? Maybe a DITA to WordPress import plugin or to Drupal or Joomla?

Currently, I don’t feel there is a good answer for the human element of DITA and wikis. I responded to Tom Johnson’s blog post when it was first posted stating that I believe there is common ground between wikis and DITA but most of that common ground is in terms of technical implementation rather than usage patterns.

I am not saying there is not a place for a native DITA wiki, but the use case is probably for collaboration among DITA authors rather than with a larger community of end users.