Lars Trieloff's Collaboration Weblog

Keith Soltys links to MadCap Flare, a new XML-based solution for editing Online Help for Microsoft Windows. The product will include following key features:

Easily create content in XML, no programming required

Probably a WYSIWYG-XML-Editor

Import existing content to save time

Import filter for Microsoft Word documents, HTML documents, RoboHelp projects, HTML Help projects, and Adobe FrameMaker? files

Generate multiple output formats

HTML, Flash, Longhorn Help, HTML Help, printed documentation and any XML format (probably via XSLT)

Enjoy unprecedented ease of use

A good user interface

Keep projects organized and on track

basic project management features as versioning and journalling.

The program is not yet released, but you can sign up for the beta program.

Marc Logemann wants to write software documentation for his projects. He is going to evaluate two approaches: xDoc/Apache Forrest and DocBook.

I am evaluating options for generating documentation for my upcoming product. While googling i only found Docbook and xDoc as standards with more or less widespread usage. Some years before, i used IBM Dita, another XML documentation project, but i dont think it got any acceptance so i dont want go back to that. --docbook versus xDoc (Apache Forrest)

As he is disencouraged by the overwhelming complexity of the DocBook DTD, he wants to start with Apache Forrest, but is rather disappointed of it's documentation and overall usability.

I settled for Apache Forrest and did the first steps in this project. Lets start with the documentation available on the apache-forrest website. I dont think it will be awarded for the most comprehensive documentation ever written, furthermore you never know when to consult the cocoon documentation and when not. --Apache Forrest - for freaks only?

In the next step he settles for DocBook and compares different XML editors. XMLSpy seems too pricy for the set of incomprehensible features (and it has problems with XML), XMetal needs macros for everyday-magic that is needed to work productive with DocBook, XMLmind XML Editor looks good, but Marc is a Java-developer, so he does not seem to have problems with typing code. oxygenXML looks like a good choice for him.

This one is really nice, its not wysiwyg but the all tested wysiwyg editors somehow didnt get it. With oxygen you get a lot of help when it comes to authoring your docbook. There are some neat samples including XInclude Variants and processing the XML file to HTML or PDF is out of the box. Correct, no seperat install of an FOP processor or anything. Just clicking the button and there you go. This is how software should be, no lengthy documentation reading for doing simple things (wink to XMetal - where i read about 20 pages for most trivial stuff). The price of 128$ (nice analogy to the bits and bytes range) is really outstanding. --how to edit docbook

I think he has made a good coice - for a developer. Less technical oriented writes may also like the Syntext Serna editor.

The translate.sourceforge.net Project offers a range of tools supporting translators of Open Source Software Projects. Among those tools is the Pootle server http://pootle.wordforge.org/, which allows web-based translation of some popular Free Software projects.

These tools are not limited to Open Source Software, you can install them on your own system and translate your own software as well.

Most users of the Eclipse-IDE, who use Subversion may already have heard of Subclipse, which offers a Subversion-implementation of the Team-API, allowing you to checkout sources from your repository and commit changes without leaving your IDE.

There is only one major drawback: It does not work. You can add files to the repository and track the changes, it will even follow file renames when using the Eclipse refactoring features, but it simply fails when it comes to committing your changes.

The reason is that Subclipse uses the Java-to-native interface to communicate with subversion. If your Subversion version does not match the version Subclipse was built against, forget it. If you are not using Microsoft Windows, forget it two times.

The solution comes in form of the Pure Java Subversion (SVN) Client Library. This library uses the command line interface of Subversion and simply works. If you would like to use it with Eclipse and Subclipse:

1. select Help->Software Updates->Find and Install->Search for new features to install and create a new update site with the URL http://tmate.org/svn/
2. Install all available features from this update site