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