Skip to content

XAware Community

Get the Flash Player to see this player.
Flash Image Rotator Module by Joomlashack.
XAware 5.6
Need Help
Webinars and Events
Advanced Tutorials
Webinars and Events

You are here: Home arrow Blogs

Untagged  20 Mar 2008 10:53 AM
Open Source Projects, Open Source Content by voconnor

Some weeks ago, I posted a question on the Eclipse Technical Writer Yahoo group asking whether writers were open-sourcing their content along with the open source Eclipse plug-ins they support and how did they do that exactly? I limited the discussion (upon reminder, thanks!) to open source Eclipse plug-ins as this was the group I was specifically querying. You can review the discussion here:

Allow me answer my own question first

At XAware, our help is currently compiled using AuthorIT and delivered as output .html and .xml files and is not specifically delivered as source content that users can then modify and compile on their own. Users can make modifications to the output .html and .xml files and that updated content will load (if done properly) from the help menu. Those content changes can be contributed back to the project for everyone's benefit. This process is documented in the XAware wiki for contributing code (see

Modifying the output help files will result, however, in a mismatch between that updated content shared in the community and the content management system we use to produce new content unless the author alerts the XAware team who can then make the changes and push it back out to the community.

It may not be the perfect solution, but it is what we have for the time being. We wanted to know if other writers were faced with the same situation.

What we discovered

The Eclipse Technical Writer community seems to agree that there really isn't an open-source help authoring tool with component content management (CCM) or content management system capabilities (CMS) that will enable sharing source content between developers, writers, and users and still allow the content to be compiled into familiar output products. As Rick Sapir wrote, "isn’t this the basic problem with using a closed-source (AIT) tool to produce open-source deliverables?" Yep, duly noted, but the problem is that the tool simply does not exist and ... and as Robert Lauriston noted, "it's highly impractical to maintain a large help system with lots of internal cross-refernces [sic] using a text editor."
Rick Catalano, who is working with a development organization to promote open development of some of the product components, writes that the most successful open document efforts were based on practices similar to those common in development. These practices being that source changes are submitted back for approval and acceptance, and then rolled into the core product for release. When the content is delivered as DITA, an XML-based open source schema for content, the authoring tools aren't an issue (any text editor will do). Additionally, the open document community is free to take the sources and use their authoring tool of choice to modify the content and deliver it back to be incorporated into the core at another time.

Interestingly, Rick Catalano brought up another point as well. His team will need to have resources in place to manage and administer the open documentation content when users start to contribute. That kind of management, similar to wiki monitoring I think, is not always accounted for in a writer’s day to day schedule, so yes, I agree, they will eventually have to figure out a way to handle that issue.

At XAware, we are currently looking into implementing help extension points that will let users contribute help content when they contribute modules. This will help users who want to contribute components. In addition, we may be able to define a set of transformations in the help to support run-time help rendering, as suggested by Markus Vaterlaus.
For now, XAware will continue to deliver the supporting content as we have, but we’ll be watching for how to improve it as our community and the need develops.

Thanks for being here! 

Comments (0)add comment

Write comment
You must be logged in to a comment. Please register if you do not have an account yet.


Get the Flash Player to see this player.
Flash Image Rotator Module by Joomlashack.
Free Training
QuickStart Packages
Image 4 Title
Image 5 Title


Which data source and BizComponent combinations do you most frequently use?


Recent Entries