<?xml version="1.0"?>

<document>

 <properties>
  <title>The Apache Portals Documentation Effort</title>
  <author email="taylor@apache.org">David Sean Taylor</author>
  </properties>

<body>

<section name="The Apache Portals Documentation Effort">

  <subsection name="Documentation Roadmap">
<p>
      This page covers how to contribute to the Apache Portals's documentation.
      We are working very hard to improve Apache Portals's documentation.  
</p>

<p>
      Below is the list of documentation items we are working on listed in order
      of priority from greatest to lowest.  We need help with them all!
</p>

<ul>
      <li>
        <b>Apache Portals Website</b>
        <ul>The Portals website needs work..</ul>
      </li>
      <li>
        <b>Jetspeed-2 Website</b>
        <UL>
        <li>The Jetspeed-2 Website needs a lot of work</li>
        <li>Each component needs its own documentation page</li>
        </UL>
      </li>
      <li>
        <b>Jetspeed-1 Website Conversion</b>
        <UL>
        <li>Jetspeed-1 Website needs to be converted to Maven</li>
        <li>Add tutorial from Bluesunrise</li>
        </UL>
      </li>
</ul>
  </subsection>
  
  <subsection name="Our Documentation Has Three States">
    <ol>
      <li>
        <strong>Infancy:</strong>  A document becomes nascent in the Wiki
        as an empty or sparsely populated page.  At this point, people continue to
        add and revise the content until it becomes mostly stable and unchanging.
        <ul><!-- FOR SPACING --></ul>
      </li>
      <li>
        <strong>Stability:</strong>  Once the document has reached a stable point, it is converted into the xdoc
        format and injected into the portals-site (or subproject) cvs modules.
        <ul><!-- FOR SPACING --></ul>
      </li>
      <li>
        <strong>Maturity:</strong>   As changes to the projects are made, the documentation
        is updated and improved via xdoc patches from the <a href="../issue-tracking.html">Issue Tracking system</a>.
        <ul><!-- FOR SPACING --></ul>
      </li>
    </ol>
  </subsection>

  <subsection name="How You Can Help">
<p>
      Now that you know what we are working on, you need to know the best ways to help.
      Content is farmed and stabilized on the <a href="../wiki.html">Apache Portals Wikis</a>
      until it is stable enough to become official documentation.  Additionally 
      questions are answered and re-answered on the mailing lists.  
      You can help the Documentation effort by:
</p>
<ul>
      <li>
        <strong>Editing The Wiki Content:</strong> Mature and stabilize the information on the <a href="wiki.html">Wiki</a>.
        <ul><!-- FOR SPACING --></ul>
      </li>
      <li>
        <strong>Filtering The Mailing List:</strong> When you see something float
        by on the mailing list that should become part of the official,
        please convert it into the appropriate xdoc format and submit it as an
        issue in our <a href="../issue-tracking.html">Issue Tracking system</a>.
        <ul><!-- FOR SPACING --></ul>
      </li>
      <li>
        <strong>Creating Xdoc Patches:</strong> If you find a typo, mistake or
        overlooked information in the official documentation, please create
        an issue in our <a href="../issue-tracking.html">Issue Tracking system</a>.
        <ul><!-- FOR SPACING --></ul>
</li>
</ul>
  </subsection>

  <subsection name="Getting The Documentation Source And Making A Patch">
    <ol>
      <li>
<p>
          <strong>Get The Source:</strong>
          Check out the latest source from the Portals CVS module.  You can learn
          about the CVS repositories <a href="../cvs-usage.html">here</a>.
          The Portals Site documentation resides in the portals-site module:
</p>
        <source><![CDATA[cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login
password: anoncvs
cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic checkout portals-site]]></source>
      </li>
      <li>
<p>
          <strong>Build The Site:</strong>
          The documenation is built using <a href="http://maven.apache.org/">Maven</a>,
          with the following command:
</p>
        <source><![CDATA[maven site:generate]]></source>

<p>
          Afterwards, you should get something like:
</p>
        <source><![CDATA[BUILD SUCCESSFUL
Total time:  20 seconds]]></source>

<p>
          You will find the built HTML in $PATH_TO_MODULE/target/docs.
</p>
      </li>

      <li>
        <strong>Make Your Changes:</strong>
        The docs are written using the Anakia Xdoc format, which you can learn about <a href="http://jakarta.apache.org/site/jakarta-site-tags.html">here</a>.
        The source files are found in the $PATH_TO_MODULE/xdocs directory, each xml file corresponding to the generated html file.
        Menu information is found in the navigation.xml files.
        <ul><!-- FOR SPACING --></ul>
      </li>

      <li>
        <strong>Make A Patch:</strong>
        <source><![CDATA[cvs diff -rNu > name_of_patch.patch]]></source>
        <ul><!-- FOR SPACING --></ul>
      </li>

      <li>
        <strong>Submit Your Changes:</strong>
        We use the <a href="../issue-tracking.html">JIRA Issue Tracking system</a> to track issues.  Once
        you have a patch, log in the Issue Tracking System
        and create a new issue in the Documentation module.  A project committer will approve the patch
        and apply it, or let you know if something should be changed.
        <ul><!-- FOR SPACING --></ul>
      </li>

      <li><strong>Thank you for helping out!</strong></li>
    </ol>
  </subsection>
</section>

</body>
</document>
