>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.

This entry was posted in dita, docbook, eclipse, xml. Bookmark the permalink.

10 Responses to >WYSIWYG XML Editting

  1. >The current problem is that most of the documentation done by Eclipse project teams is strictly HTML. HTML isn't an optimal single sourcing format. I don't know of any teams using DITA at Eclipse, I do know of product teams using DITA.My goal was to involve the community via Eclipsepedia because that's already available and has a breadth of documentation on it already. It's a matter of organizing it and sourcing it from there.

  2. Eike Stepper says:

    >We do: http://www.eclipse.org/cdo/documentation/manual_20.phpAnd we also use Serna for authoring the DTA sources. I like it ;-)Cheers/Eike

  3. David Carver says:

    >@Chris I know that all of WTP's documentation is maintained and updated in DITA and regenerated. And from the looks of things the original HTML that was generated for Eclipse can from DITA documentation source files. XSL Tools maintains it's documentation in DocBook and generates to html. As Eike said, CDO also uses it. And I would suspect that original documentation developed by IBM and contributed to eclipse is DITA since that appears to be what IBM uses internally.

  4. >Good to see other Eclipse projects using DITA or DocBook… I still think that's the rarer case though.I still think that DITA and DocBook have high barrier to entry… as users would have to interact with some SCM system generally in order to contribute documentation. The reason I prefer using Eclipsepedia/Wikitext is that users only have to interact with a browser and a online wiki. Similar to how users contribute to Wikipedia… it's pretty simple.In the end, projects have their choice. I also hope that whatever we choose, we make it easier for our users and adopters to contribute back documentation.

  5. David Carver says:

    >@Chris Advantageous and disadvantegous to all forms. Personally, I think wiki markup going beyond the basics gets to confusing for most people. Plus from a pure semantics point it mixes too much layout with the content. DITA abstracts it away too much, and of course me being a fan of DocBook I think it strikes the right balance between structured content and markup.Again, each his own, but I agree the docs need to be single sourced. HTML is not the way to do it.

  6. >I'm not a huge fan of wiki syntax either… but I find it easier to do than docbook/dita. I'd point towards the success of Wikipedia…If you match wiki markup with something like FCKEditor / TinyMCE… you give users a familiar "Word" type interface to do the documentation… we remove the wiki syntax barrier…

  7. >Dave, this makes an excellent architecture council topic. I will file a bug along with the mail I already sent. I think the architecture council should put out a recommendation to Eclipse projects to do their documentation in some way (or multiple ways with pluses and minuses with each approach). In the end, I want us to make it easier to contribute documentation!

  8. David Carver says:

    >Excellent topic for the Architecture Council. Goes along with my more agile recommendation for projects as well.Oh and I'd counter your Wikipedia with WhoUsesDocBook for documentation as a single source:http://wiki.docbook.org/topic/WhoUsesDocBook🙂

  9. Holger says:

    >I like (and I'm using) both Vex and WikiText.Vex is a really good editor for structured text and can be used in particular by non-engineers. WikiText converts different Wiki languages into XHTML = structured text. So, why not use both: WikiText to parse Wiki pages and Vex as WYSIWYG-Editor?By the way, Vex is not only useful for documentation but also used in linguistics to create annotated text corpora (see http://sourceforge.net/apps/trac/pacx/wiki/PacxUsers).

  10. skleinei says:

    >Very interesting read.I just wanted to let you know about a single-source publishing solution based on Atlassian's Confluence Wiki: The Scroll Wiki Exporter which converts trees of wiki pages to DocBook and PDF. Other formats are yet to come.-Stefan(K15t Software)

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s