cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Reinhard Poetz <reinhard_po...@yahoo.de>
Subject Re: New structure of Cocoon documentation and doc repositories
Date Thu, 30 Dec 2004 08:59:40 GMT
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


Mime
View raw message