You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Reinhard Poetz <re...@apache.org> on 2004/12/29 14:57:05 UTC
New structure of Cocoon documentation and doc repositories
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?
If people are fine with this, I'm going to setup repository (A) and (B) next
week and put them into SVN.
--
Reinhard
Re: New structure of Cocoon documentation and doc repositories
Posted by David Crossley <cr...@apache.org>.
Reinhard Poetz wrote:
> David Crossley wrote:
> >Reinhard Poetz wrote:
> [snip]
> >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
>
> sorry, overlooked this
>
> >as well as all of the "generated" documentation for both the top-level
> >and the version-specific docs.
>
> is it still Apache-wide policy to have the generated docs into a repository?
Yes.
> Wouldn't be a script that generates the whole documentation on one of the
> Apache
> machines and publishes it, do the same?
Here we go again. Yes, and there are plans to do that. However,
it takes human beings to get motivated. Setting up a test
system (either Forrestbot or Cocoon or both) on brutus
managed by Apache Gump project) is the next step. I have asked
a couple of time for access there - need another ping.
> >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
>
> I wouldn't do this. I think it should be easily reachable by a top-level
> tab,
> but the content should come from the latest "manual" as our concepts
> slightly
> change over time.
Yes, i was going through the possibilities. You are correct.
> >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.
>
> My "new docs" efforts aim at Cocoon 2.2 but should work with 2.1 too. It
> should
> only require some changes in the tabs.xml of 2.1-repository.
I look forward to seeing that.
[snipped the rest, as i gotta go out tonight, will answer later]
--David
Re: New structure of Cocoon documentation and doc repositories
Posted by Reinhard Poetz <re...@yahoo.de>.
David Crossley wrote:
> 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
sorry, overlooked this
> as well as all of the "generated" documentation for both the top-level
> and the version-specific docs.
is it still Apache-wide policy to have the generated docs into a repository?
Wouldn't be a script that generates the whole documentation on one of the Apache
machines and publishes it, do the same?
>
> 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
I wouldn't do this. I think it should be easily reachable by a top-level tab,
but the content should come from the latest "manual" as our concepts slightly
change over time.
> 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.
My "new docs" efforts aim at Cocoon 2.2 but should work with 2.1 too. It should
only require some changes in the tabs.xml of 2.1-repository.
>
> 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.
I have to admit that the tabs concept of Forrest is very confusing for me. I'm
not able to "think in" this way. But after playing with it, I got what I want. I
try to explain it in other words:
The Cocoon website should provide following main tabs:
| Project | Community | Getting Started | Documentation
The content of these tabs are generated out of *two* repositories:
- Project and Community out of a "global" repository
- Getting Started and Documentation by the latest release docs repository
So let's look into tabs.xml of the "global" repository:
<tab id="" label="Project" dir="" indexfile="index.html"/>
<tab id="community" label="Community" dir="community" indexfile="index.html"/>
<tab id="getting-started" label="Getting started"
href="http://cocoon.apache.org/2.2/getting-started/index.html"
/>
<tab id="docs" label="Documentation"
href="http://cocoon.apache.org/2.2/index.html"
/>
... and the docs repository of the 2.2 manual could look like this:
<tab id="project" label="Project" href="http://cocoon.apache.org"/>
<tab id="community" label="Community"
href="http://cocoon.apache.org/community/index.html"/>
<tab id="getting-started" label="Getting started" dir="getting-started"
indexfile="index.html"/>
<tab id="docs" label="Documentation" dir="" indexfile="index.html">
<tab id="docs-2.1" label="2.1 docs"
href="http://cocoon.apache.org/2.1/index.html"/>
<tab id="docs-2.0" label="2.0 docs"
href="http://cocoon.apache.org/2.0/index.html"/>
</tab>
After generating the docs of both repositories, the result docs of the second
repository is copied into the right directory of the result docs of the first
repository. (and also the content of all other manuals)
As you can see, navigating to "Documentation" gives access to the old docs
through second-level tabs (assuming that 2.2 is the latest):
1st-level-tabs: | Project | Community | Getting Started | "Documentation"
2nd-level-tabls 2.1-docs | 2.0-docs | 1.x-docs
The left-side navigation bar contains the structure of the manual.
>>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.
Right for the global repository, but I don't think so for the "manual
repository" of 2.2. I want an empty docs repository and I want a doc type that
makes it easier for doc authors to write (HTML or XHTML) as they should be able
to use tools like Mozilla Composer.
> 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.
Maybe I'm doing the same as what you call "dummy" tabs. I haven't looked into
the Forrest docs.
WDYT?
--
Reinhard
Re: New structure of Cocoon documentation and doc repositories
Posted by David Crossley <cr...@apache.org>.
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