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.
- Please keep the dot-point numbers, just add new ones at the bottom. In this way we can just refer to item numbers during email discussion.
- Please add your comments or relevant links below any item.
- If you want to make major changes then please be sure to discuss that on cocoon-dev.
Outline of requirements and issues
Forrest to assist with building Cocoon system documentation.
RELATED LINKS
1.Using Forrest
1.HowToForrestTransition
1.Lots of discussion on cocoon-docs in late-March 2003
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
1.(ds) I believe I have successfully adapted earlier work to transform Cocoon docs to doc-v11 (and other) dtds.
1.(ds) I have submitted a first draft. Issues remain. Please help resolve. See HowToForrestTransition
After Cocoon xdocs are sucessfully transformed, the xdocs in CVS will be updated to be document-v11 type.
PROPOSAL
- One person needs to update CVS when they are happy with the transition, then others can help to refine it.
READER COMMENTS
1.(ds) And do we delete legacy dtds or simply remove any configuration (schema) reference to them? (dc) Added new item 15 below to deal with this.
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
1.(ds) How will we synchronize this with Forrest updates? (dc) ? Not sure what you mean Diana.
Expect a few people to help, especially during the transition of xdocs.
PROPOSAL
- At some stage we are going to need to just break the docs/webapp-docs parts of cocoon-2.1 and this disruption will take a few people to put it back together.
The documents that are published by Forrest need to be subsequently checked-in to the xml-site CVS.
DECISION
READER COMMENTS
1.(ds) Do you mean the live site cvs? Why? I thought the whole point of Forrest automation was to remove this step?
1.(dc) Yes because this is how all xml.apache.org sites need to currently do this.
1.(dc) ToDo: See current email discussion and gather the issues when it is finished.
1.(bd) I think Forrestbot aims to automate this, see this thread
1.(jt) We have a bunch of Forrest sites updating every hour, visible at http://forrestbot.cocoondev.org. Automatic or manually triggered update of xml-site/targets/* is possible, but not enabled by default. RELATED LINKS
- 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
- Forrest cvs head now has a cvs tag called "stable".
Decide which "tabs" to use. See Apache Incubator for one example of tab use.
DECISION
- Use the tabs that are suggested below. These are easy to re-arrange.
READER COMMENTS
- (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
- Do not show the author of the home page. Show authors of all other pages. Review the <author> element of all xdocs.
READER COMMENTS
- (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.
- (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.
- (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.
- (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
- discussion about single status.xml versus separate files
Elevate doc-related changes and todo documents to top-level status file.
PROPOSAL
READER COMMENTS
- (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
- (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
- Follow whatever Forrest decides to do.
READER COMMENTS
- (dc) How do we we mark them as deprecated?
- (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
- 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
- (dc) I would rather leave this until after transition.
Perhaps the navigation/organization of pages should be revisited at the same time.
PROPOSAL
- Leave this until after transition.
READER COMMENTS
- (dc) Perhaps this would make the job too big and so may delay it.
- (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
- Leave this issue until after transition is finished. Forrestbot already addresses part of this need.
RELATED LINKS
1.cocoon-dev email: staging/promotion
1.forrest-dev email: RT: Site versioning, staging and deployment (Careful: There are followups with slightly different thread names.)
1.cocoon-docs email: Staging mechanism
From which branch does the website get generated - head or release branch?
PROPOSAL
READER COMMENTS
- (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
- cocoon-docs email: Out of which branch should the website be published?
Recent major changes
- 2003-04-06 Noted some decisions and fine-tuned the text.
Some relevant email discussion and documents
To Do
- Extract some more requirements and issues from Nikola Ken summary
- Fine-tune and prioritise this list of issues, then develop the actual proposal (see email).
See also
Abbreviated names of readers
For readability's sake: