Guidelines to Publish Project Documentations

Added by Hasan, last edited by Hasan on Oct 07, 2008  (view change)

Project documentations will be published under http://trialox.org/projects/, e.g., the documentations of project org.trialox.jaxrs is available under http://trialox.org/projects/org.trialox.jaxrs/.

Adding a project document to its site

To add a project document to its site, follow the steps below:

  1. Follow the guidelines on "Committing, versioning and code reviewing" for updating a project
  2. If src/site/resources does not exist, create it
  3. Write your document in a format recommended below
  4. Create subdirectory under src/site/resources, if needed, and place your documents under this directory
  5. Create or update src/site/site.xml accordingly

Naming, language, and formats

Directories and files should be named in lowercase. Documentations must be available in US English. Documentations in other languages may be provided where necessary. In general, we should use XHTML 1.1 format (http://www.w3.org/TR/xhtml11/) to write documents describing our projects. As character encoding we use UTF-8. Validate with http://validator.w3.org/ before publishing them. The use of other formats are not recommended.

Example

Suppose we want to have a document called tutorial_1.xhtml accessible under http://trialox.org/projects/org.trialox.jaxrs/tutorials/tutorial_1.xhtml. Then

  1. create src/site/resources/tutorials under org.trialox.jaxrs.
  2. Place tutorial_1.xhtml under src/site/resources/tutorials
  3. Update src/site/site.xml to look like this 
    <?xml version="1.0" encoding="UTF-8"?>
<project>
  ...
  <body>
  ...
    <menu name="Tutorials">
      ...
      <item name="Tutorial 1" href="tutorials/tutorial_1.xhtml"/>
    </menu>
    ...
  </body>
</project>




Labels

 
(None)