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:
Documentation Use Case
Thinking about the general OpenCMIS use discovery process, I imagine something like:
- user googles for a Java CMIS API
- user gets to the OpenCMIS home page
- user downloads (or use Maven) to get a specific RELEASE or SNAPSHOT packages
- 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/ 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"
Deliverables
Our release process could produce:
- Live: Having aligned Maven and CMS aligned, e.g. for version 0.3.0,something like:
- chemistry.apache.org/java/
- chemistry.apache.org/java/0.3.0/
- chemistry.apache.org/java/0.3.0/maven/
- chemistry-docs.zip: can be then create as as export + template of the per version specific tag.
Doubts
- Is the chemistry-docs.zip at all needed?
- Can we use MarkDown as input for standard Maven Doxia (e.g. to produce a per release PDF)?
