svn commit: r786057 - /websites/staging/chemistry/trunk/content/java/documentation-lifecycle.html

[bu...@apache.org]

Author: buildbot
Date: Fri Feb 25 16:32:03 2011
New Revision: 786057

Log:
Staging update by buildbot

Modified:
    websites/staging/chemistry/trunk/content/java/documentation-lifecycle.html

Modified: websites/staging/chemistry/trunk/content/java/documentation-lifecycle.html
==============================================================================
--- websites/staging/chemistry/trunk/content/java/documentation-lifecycle.html (original)
+++ websites/staging/chemistry/trunk/content/java/documentation-lifecycle.html Fri Feb 25 16:32:03 2011
@@ -174,23 +174,55 @@ Apache Chemistry - 
            </td>
            <td height="100%">
              <!-- Content -->
-             <div class="wiki-content"><p>Thinking about the general OpenCMIS use discovery process, I imagine something like:</p>
+             <div class="wiki-content"><p><strong><em>This page is a proposal / design page for OpenCMIS documentation</em></strong></p>
+<h2 id="documentation_deliverables_current">Documentation Deliverables (current)</h2>
+<p>At the moment (0.2.0-incubating --&gt; 0.3.0) we deliver the following documentation:</p>
+<ul>
+<li><a href="http://chemistry.apache.org/java">Apache CMS driven public website</a><br />
+</li>
+<li>chemistry-docs-<version>.zip containing Javadocs + latest snapshot of public docs</li>
+<li><a href="http://incubator.apache.org/chemistry/maven-site/">Maven generated reports</a> (tests reports + project info) per <version> </li>
+</ul>
+<h2 id="documentation_use_case">Documentation Use Case</h2>
+<p>Thinking about the general OpenCMIS use discovery process, I imagine something like:</p>
 <ol>
-<li>they Google for a Java CMIS api</li>
-<li>they get to the <a href="http://chemistry.apache.org/java">OpenCMIS home page</a></li>
-<li>they download (or use maven) to get the packages</li>
-<li>they keep on browsing on the live site (for HOWTOs and Javadocs or other reports)</li>
+<li>user googles for a Java CMIS API</li>
+<li>user gets to the <a href="http://chemistry.apache.org/java">OpenCMIS home page</a></li>
+<li>user downloads (or use Maven) to get a specific RELEASE or SNAPSHOT packages </li>
+<li>user keeps on browsing on the live site (for HOWTOs and Javadocs / project info)</li>
 </ol>
-<p>I think we could skip the docs package, as long as we version live documentation sites, meaning that:</p>
+<h2 id="documentation_lifecycle_proposed">Documentation lifecycle (proposed)</h2>
+<p>Fundamental requirement to change the documentation lifecycle as is is that we have 
+<strong>no online versioning of our documentation</strong> and the chemistry-docs.zip package is too
+weak.</p>
+<p>Since with Apache CMS versioning documentation is as easy as a SVN tag, I suggest we 
+simplify the documentation process as follows:</p>
 <ul>
-<li>List item chemistry.apache.org/java --&gt; <ul>
-<li>always keeps docs for the current SNAPSHOT version</li>
-<li>links to all release packages and per version documentation sites</li>
-<li>contains roadmap and design information</li>
+<li><strong>http://chemistry.apache.org/java/opencmis.html</strong> remains the entry point and<ul>
+<li>links to all release packages and <strong>per version documentation sites</strong></li>
+<li>always keeps docs for the current SNAPSHOT version (even design + proposals)</li>
+<li>contains Roadmap and centralized information</li>
+</ul>
+</li>
+<li><strong>http://chemistry.apche.org/java/{version}</strong> (linked by the main page)<ul>
+<li>will keep the documentation archive for a specific release {version}</li>
+<li>these snapshots can be tagged upon release by maven</li>
+<li>the maven generated site (with Javadocs and test reports) gets generated under a subfolder called <em>"maven"</em></li>
 </ul>
 </li>
-<li>chemistry.apache.org/java/<version> --&gt; linked by the main page, will keep the archive for a specific release <version>, snapshot (AFAIK it's SVN, so we could just tag it upon release?)</li>
-</ul></div>
+</ul>
+<p>This way we can have aligned Maven and CMS aligned, so that e.g. for version 0.3.0,
+our release process can produce something like:</p>
+<ul>
+<li>chemistry.apache.org/java/</li>
+<li>chemistry.apache.org/java/0.3.0/</li>
+<li>chemistry.apache.org/java/0.3.0/maven/ </li>
+</ul>
+<p>The chemistry-docs.zip can be then create as as export + template of the <strong>per version specific tag</strong>.</p>
+<h2 id="doubts">Doubts</h2>
+<ol>
+<li>Is the chemistry-docs.zip at all needed?</li>
+</ol></div>
              <!-- Content -->
            </td>
           </tr>