Bogor Website - Contributing A Bogor Documentation

1. Documentation Tools

Bogor documentation is written using Docbook. Docbook is an excellent markup language for writing technical documentations (that do not have a lot of mathematical formulae). A DocBook document can be easily translated to HTML, PDF, or PS files. More information about DocBook can be found at http://en.wikipedia.org/wiki/Docbook.

The necessary tools to translate a DocBook document can be found at: https://robby.user.cis.ksu.edu/bogor/documentation/tools. In order to make the process of writing documentation easier, one would need a good XML editor such as XMLMind XML Editor that allows structured editing of DocBook documents with context-sensitive assistant. XMLMind provides a Standard Edition for free; although it has limited functionality, it is very usable.

Using the Ant build tool is the preferred way to automate document build process, and Eclipse has a good Ant integration. See the https://robby.user.cis.ksu.edu/bogor/documentation/build.xml file for an example Ant file. See the Ant manual for more information about Ant build file. If you use XMLMind's XML Editor Standard Edition, you can alternatively take advantage of its integrated converter to translate your DocBook files to other formats (see XMLMind's editor menu: DocBook -> Convert Document). This requires the Personal Edition of RenderX and the XMLMind's RenderX add-on (see XMLMind's editor menu: Options -> Install Add-ons).

2. Posting A Documentation in the Bogor Website

In order to post a documentation in the Bogor website, you need to log in first. If you are not an Author, an Editor, or a Publisher, then you can submit your content by clicking "Submit Doc" in the User Menu. You will be presented with a submission form that looks similar to the figure below.

Figure 1. Bogor Documentation Submission Form

You need to fill in the document title, its category, a brief summary for the intro text, and the actual main text. The main text should be an HTML file that is translated from the source DocBook document. More specifically, copy and paste from the first <hr> tag after the <body> tag to the last </div> tag before </body> (assuming that you select "No WYSIWYG" in "Your Details"'s "User Editor"). If you are a Publisher, you can choose to change the document from "Unpublished" to "Published" in the "Publishing" tab. Otherwise, the website administrator or a Publisher will need to approve your submission. Do not forget to save your changes by clicking the disk button.