>Chris has started discussion on ways to make it easier for eclipse documentation to be updated. He has rightly stated that the state of eclipse documentation leads a lot to be desired. The docs are stored in a variety of formats and in a variety of locations. WikiText is a good contender for helping to help reduce the barrier to entry for the community to contribute. I also agree that single sourcing should occur as well. However it is going to take time to get all the necessary pieces in order, and honestly I’m not sure it’s going to happen quickly. Converting documents can be a time consuming thing as well. However, how can we make it easier for users to continue to contribute to the existing documentation during the transition period that may occur?
If the documentation was originally created by IBM and the original code was contributed from IBM, then more than likely that existing documentation resides in DITA xml files. Using the DITA open source toolkit one can generate the eclipse help and toc.xml files. However, for most people working at the XML tag level is not enjoyable. Just as for some working with some of the cryptic Wiki markup isn’t enjoyable as well. Some projects also store their help format in DocBook format. This is a popular format on many open source projects within the linux community. Both DocBook and DITA allow for single sourcing of the content. So how can one make editing and creating these files easier with an open source solution?
Syntex has recently announced they are open sourcing their XML Editor. It provides a WYSIWYG editor for DocBook and DITA files. Eclipse also has the VEX editor, which is in the WTP Incubator. However, the status of VEX is that it needs lots of work to get it to the point that it can be competitive with Syntex or other commercially available options.
For now, those that need to work with existing eclipse documentation, that is stored in DocBook or DITA formats, you may want to consider the free XML editor provided by Syntex. It may help lower that barrier to entry for both the contributor and or the committer that has to maintain the documents.