svn commit: r1074619 - /chemistry/site/trunk/content/java/documentation-lifecycle.mdtext

[ga...@apache.org]

Author: gabriele
Date: Fri Feb 25 16:31:58 2011
New Revision: 1074619

URL: http://svn.apache.org/viewvc?rev=1074619&view=rev
Log:
Updated docs proposal

Modified:
    chemistry/site/trunk/content/java/documentation-lifecycle.mdtext

Modified: chemistry/site/trunk/content/java/documentation-lifecycle.mdtext
URL: http://svn.apache.org/viewvc/chemistry/site/trunk/content/java/documentation-lifecycle.mdtext?rev=1074619&r1=1074618&r2=1074619&view=diff
==============================================================================
--- chemistry/site/trunk/content/java/documentation-lifecycle.mdtext (original)
+++ chemistry/site/trunk/content/java/documentation-lifecycle.mdtext Fri Feb 25 16:31:58 2011
@@ -16,20 +16,58 @@ Notice:    Licensed to the Apache Softwa
            specific language governing permissions and limitations
            under the License.
 
+***This page is a proposal / design page for OpenCMIS documentation***
+
+## Documentation Deliverables (current) ##
+
+At the moment (0.2.0-incubating --> 0.3.0) we deliver the following documentation:
+
+  - [Apache CMS driven public website][1]  
+  - chemistry-docs-<version>.zip containing Javadocs + latest snapshot of public docs
+  - [Maven generated reports][2] (tests reports + project info) per <version> 
+
+##Documentation Use Case##
+
 Thinking about the general OpenCMIS use discovery process, I imagine something like:
 
- 1. they Google for a Java CMIS api
- 2. they get to the [OpenCMIS home page][1]
- 3. they download (or use maven) to get the packages
- 4. they keep on browsing on the live site (for HOWTOs and Javadocs or other reports)
+ 1. user googles for a Java CMIS API
+ 2. user gets to the [OpenCMIS home page][3]
+ 3. user downloads (or use Maven) to get a specific RELEASE or SNAPSHOT packages 
+ 4. user keeps on browsing on the live site (for HOWTOs and Javadocs / project info)
+
+
+##Documentation lifecycle (proposed) ##
+
+Fundamental requirement to change the documentation lifecycle as is is that we have 
+**no online versioning of our documentation** and the chemistry-docs.zip package is too
+weak.
+
+Since with Apache CMS versioning documentation is as easy as a SVN tag, I suggest we 
+simplify the documentation process as follows:
+
+  - **http://chemistry.apache.org/java/opencmis.html** remains the entry point and
+      - links to all release packages and **per version documentation sites**
+      - always keeps docs for the current SNAPSHOT version (even design + proposals)
+      - contains Roadmap and centralized information
+  - **http://chemistry.apche.org/java/{version}** (linked by the main page)
+      - will keep the documentation archive for a specific release {version}
+      - these snapshots can be tagged upon release by maven
+      - the maven generated site (with Javadocs and test reports) gets generated under a subfolder called *"maven"*
+
+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:
+
+  - chemistry.apache.org/java/
+  - chemistry.apache.org/java/0.3.0/
+  - chemistry.apache.org/java/0.3.0/maven/ 
+
 
+The chemistry-docs.zip can be then create as as export + template of the **per version specific tag**.
 
-I think we could skip the docs package, as long as we version live documentation sites, meaning that:
+##Doubts##
 
-  - List item chemistry.apache.org/java --> 
-      - always keeps docs for the current SNAPSHOT version
-      - links to all release packages and per version documentation sites
-      - contains roadmap and design information
-  - 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?)
+ 1. Is the chemistry-docs.zip at all needed?
 
-  [1]: http://chemistry.apache.org/java
\ No newline at end of file
+  [1]: http://chemistry.apache.org/java
+  [2]: http://incubator.apache.org/chemistry/maven-site/
+  [3]: http://chemistry.apache.org/java
\ No newline at end of file