cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@apache.org>
Subject Re: New structure of Cocoon documentation and doc repositories
Date Wed, 29 Dec 2004 23:06:52 GMT
Reinhard Poetz wrote:
> 
> If we talk about documentation we usually mean all the documents available 
> at
> http://cocoon.apache.org. I think it's time to look at our documentation in 
> a more differentiated way.
> 
> Currently we have a
> 
>  - project documentation (who we are, download, ...)
>  - manuals for each minor and major release (1.x, 2.0, 2.1)
> 
> Project documentation and manuals are mixed up. That's the first thing we 
> have to improve as they have different lifecycles.
> 
> I propose following structure:
> 
>  (A)
>  - Project
>    - Vision
>    - License
>    - History
>    - ...
>  - Community
>    - How to contribute
>    - Wiki
>    - Issue tracking
>    - SVN
>    - ...
>  ............................................................
>  (B)
>  - Getting started
>    - Your first example in two minutes
>    - Base "concepts" (pipelines, flow, SoC, forms)
>    - Cocoon tutorial introducting into these base concepts
>     (Bertrand's tour block)
>    - ...
>  - Core documentation
>    - ...
> 
> (A) and (B) are *separate* Forrest repositories.
> 
>  (A) ... contains Project and Community
>          URL: http://cocoon.apache.org
>          SVN: http://svn.apache.org/repos/asf/cocoon/project-docs
> 
>  (B) ... contains the *latest* manual
> 
>          URL: http://cocoon.apache.org/2.2/ and
>               http://cocoon.apache.org/2.2/getting-started/
> 
>          SVN:
>          http://svn.apache.org/repos/asf/cocoon/trunk/src/documentation
> 
>          (older manuales are reachable through 2nd-level-tabs.
> 
> Following this structure we ensure stable URLs, have the documentation as
> close to the sources as possible, one repository for one concern and we can 
> produce manual and getting-started PDFs with default features.
> 
> Other thougths?

We already do have a separate repository for that (A):
http://svn.apache.org/repos/asf/cocoon/site/
It already contains the sources for "project" and "community" stuff
as well as all of the "generated" documentation for both the top-level
and the version-specific docs.

Some other documentation could be separated out from the
version-specific documentation. For example, some of the "concepts"
docs at /userdocs/concepts/* could move up to the top-level.
However one trouble with doing that, is that then people would
not have all of the documentation available locally at
localhost:8888/docs

Regarding (B). The "latest" should be the current "release", i.e.
currently 2.1 branch. The "trunk" 2.2 docs should certainly be
available as well.

I am not sure that "tabs" are the best way to do that.
After a while we will have too many tabs. Perhaps i am not
understanding your concept yet.

If it helps with Cocoon planning, we recently went through this
at Apache Forrest. We have project/community docs in one repository,
then the "Documentation" and "Howto" tabs come from the release branch.
The "in development documentation", i.e. trunk, is also available.
We didn't use tabs for that. See the Documentation section on the
"Welcome" tab. Also Apache Lenya have recently done a similar thing.
Not saying that Cocoon should do it that way, just for ideas.

> If people are fine with this, I'm going to setup repository (A) and (B) 
> next week and put them into SVN.

I don't think that you need to do anything - we already have
those repositories set up.

The task seems to be more about how to merge the "generated"
documents from the separate repositories. It is easy with the
current Cocoon docs - there is only one tab and the 2.1 and 2.0
slot in separately. More tabs make it difficult. At Forrest we
are generating "dummy" tabs as a workaround until we can find
how to do it better.

--David

Mime
View raw message