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
