Note: Some parts of this document are not relevant anymore since Cocoon now has its docs built by Forrest. The problem areas are now the generation of the docs via the webapp.

Background

This is an evolving proposal to determine how to smoothly enable the Cocoon documentation to be built by Apache Forrest. The main issue is that the Cocoon xdocs are still in an old xdocs format and Cocoon still uses very old stylesheets to process those documents when running Cocoon as a webapp.

Procedure

Let us start by determining the dot-points in the "Outline" section below, to express requirements and issues.

Outline of requirements and issues

Forrest to assist with building Cocoon system documentation.

RELATED LINKS

Forrest to automatically (or by manual trigger) generate the website at cocoon.apache.org/

DECISION

How will people who download just Cocoon, be able to locally build and work with its documentation? Do they need to install Forrest separately, or does Cocoon still build its own documentation using its own set of stylesheets?

PROPOSAL

Cocoon xdocs need to be transformed to document-v11 DTD. Forrest has stylesheets, DTDs, anttasks, and XML validation to assist with this.

PROPOSAL

READER COMMENTS

After Cocoon xdocs are sucessfully transformed, the xdocs in CVS will be updated to be document-v11 type.

PROPOSAL

READER COMMENTS

Simultaneously with #5, the Cocoon XSLT stylesheets, DTDs, and sitemaps will need to be updated to reflect the document-v11 from Forrest.

PROPOSAL

READER COMMENTS

Expect a few people to help, especially during the transition of xdocs.

PROPOSAL

The documents that are published by Forrest need to be subsequently checked-in to the xml-site CVS.

DECISION

READER COMMENTS

RELATED LINKS

  1. PATCH: small news update patch for cocoon gettogether - provides overview of the current cumbersome process to update the Cocoon website.

Use a consistent version of Forrest during the transition phase.

DECISION

Decide which "tabs" to use. See [[http://incubator.apache.org/|Apache Incubator]] for one example of tab use.

DECISION

READER COMMENTS

  1. (bd) I suggest "Home, Usage, Reference, Wiki, Links". "Usage" would include FAQs, tutorials and How-Tos, there is certainly a better name than "usage" for this. "Wiki" would be just one page with info on the wiki role and a link to it.

Decide whether we want to show the "authors" of each document (which may not be relevant as it is a group effort).

PROPOSAL

READER COMMENTS

  1. (dc) Authors should remain hidden, especially for general documents like the home page. Also many CVS mistakes have been made where a minor patch contributor is listed as an "author". Too easily abused. Also some pages still contain the author of another page which was used only as a template.
  2. (ds) This may be appropriate for core docs, but I think allowing authors to have their names on How-Tos will increase the incentive to contribute. See also http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=102552672926362&w=2 I personally like the idea of giving credit to those submitting revision patches. This helps users understand what has changed. See an example of this at: http://xml.apache.org/cocoon/howto/howto-paginator-transformer.html.

  3. (dc) I agree that contributors get recognition as shown with howto-paginator-transformer. However this is a different issue. The xml element document/header/author is what we are concerned about here.
  4. (dc) The author of any "group effort" page could be "cocoon-dev".

The status documents (changes, todo) need to merge into status.xml

DECISION

READER COMMENTS

  1. discussion about single status.xml versus separate files

PROPOSAL

READER COMMENTS

  1. (ds) See status-docs.xml in transition trial run sample files.

Need a mechanism to enable existing and future (with any reorganization) redirect pages.

PROPOSAL

READER COMMENTS

  1. (dc) I would rather leave this until after transition.

Do the old documnet-v10 DTDs and OASIS Catalog entries need to remain in Cocoon CVS? Other people may be still using them for their own projects.

PROPOSAL

READER COMMENTS

  1. (dc) How do we we mark them as deprecated?
  2. (dc) Or perhaps we just delete them and people need to use an old version of Cocoon if they need to still use the old document-v10 DTDs. This sounds better because if we keep the DTDs then that implies that we keep the stylesheets/sitemaps to go with them (yikes, management nightmare).

RELATED LINKS

  1. forrest-dev email: PROPOSAL: DTD Versioning

Decide if Cocoon needs its own skin (to protect its identity/brand) before/shortly after transition, given the fact many sites are adopting the default skin and given the prospect of top-level project status.

PROPOSAL

READER COMMENTS

  1. (dc) I would rather leave this until after transition.

Perhaps the navigation/organization of pages should be revisited at the same time.

PROPOSAL

READER COMMENTS

  1. (dc) Perhaps this would make the job too big and so may delay it.
  2. (ds) Transition first and reorganize later!! First, we don't even have an efficient redirect mechanism in place. Second, transitioning will save me tons of time (which I could then devote to other doc concerns) as I won't have to perform manual updates to the live site.

Staging mechanism for quality control of website production

PROPOSAL

RELATED LINKS

From which branch does the website get generated - head or release branch?

PROPOSAL

READER COMMENTS

  1. (dc) It is currently generated from the release branch. Those xdocs are meant to be always in sync with the head of CVS. The documentation does describe the head of CVS and we do not maintain any separate "release" version of the docs (rather we put notes in the documentation to indicate which branch applies). So why do we not generate the website from the head of CVS? The only reason that i can think of is that the "changes.html" on the website describes the current release branch and not all relevant changes to head have gone into release branch, so the "changes" documents are necessarily different.

RELATED LINKS

  1. cocoon-docs email: Out of which branch should the website be published?

Recent major changes

Some relevant email discussion and documents

To Do

See also

Abbreviated names of readers

For readability's sake:

ForrestProposal (last edited 2009-09-20 23:42:15 by localhost)