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
