Re: Website management [WAS Re: resurrect the Cocoon documentation]
Hi all, I have just migrated to maven site generation and XDOC format the cocoon-main-site [1] and also published the re-generated pages: please take a look at our website and let us know if there is something to fix. I'll continue this migration process for all other subsites under [2]. While taking a closer look to main site content, I've noticed some issues: * News in home page MUST be updated: I think we can add there the release of C3 alpha-2 and alpha-3 and the availability of C2.1 and C3 samples in cocoon.zones.apache.org * Professional Services [3]: some links are broken + I would like to add my company (Tirasa); other interested? * Weblogs [4]: some links are broken + I would like to add my own blog; other interested? * Products [5]: latest HippoCMS releases are not based on Cocoon anymore + MindQuarry seems not to be operational anymore + I would like to add Hippo Cocoon Toolkit [6]; other interested? * Live Sites [7]: each entry there should be reviewed * How to contribute [8]: it's all about how to run Daisy for documentation; I would wipe it completely and replace with something more general about how to contribute to Cocoon * How to publish docs [9]: obsolete, update or remove * How to build the site locally [10]: obsolete, update or remove * Releasing Cocoon [11]: update / remove Daisy information * Project Team [12]: someone went emeritus, new people has been added WDYT? [1] https://svn.apache.org/repos/asf/cocoon/trunk/site/cocoon-main-site [2] https://svn.apache.org/repos/asf/cocoon/trunk/site/ [3] http://cocoon.apache.org/1271_1_1.html [4] http://cocoon.apache.org/1271_1_1.html [5] http://cocoon.apache.org/1365_1_1.html [6] https://forge.onehippo.org/gf/project/hct/ [7] http://cocoon.apache.org/706_1_1.html [8] http://cocoon.apache.org/1273_1_1.html [9] http://cocoon.apache.org/1418_1_1.html [10] http://cocoon.apache.org/1256_1_1.html [11] http://cocoon.apache.org/1199_1_1.html [12] http://cocoon.apache.org/team-list.html On 17/03/2012 13:48, Simone Tripodi wrote: > +1 for option #2, I like keeping the doc under control and in a format > can be deployed wherever :) > > For that purpose, I just launched the VOTE thread for the Thien Skin 1.0.1. > > Thanks for leading this, all the best! > -Simo > > http://people.apache.org/~simonetripodi/ > http://simonetripodi.livejournal.com/ > http://twitter.com/simonetripodi > http://www.99soft.org/ > > > > 2012/3/16 Francesco Chicchiriccò : >> Hi all, >> yesterday, while looking at cocoon.zones.apache.org, I've spent some time at >> our website, and the e-mail below came into my mind. >> >> I believe we should act in this respect as soon as possible, since our >> outdated website is all but attractive and informative: think only that >> every page reports "Errors and Improvements? If you see any errors or >> potential improvements in this document please help us: View, Edit or >> comment on the latest development version (registration required)." pointing >> to a non-existing Daisy instance. >> >> Taking the attached e-mail into account, I think we should choose whether: >> >> 1. try to resurrect a Daisy instance in our jail - with Betrand's help / >> manage somehow 2.1 docs with forrest; >> >> 2. use Cocoon to parse existing HTML files (for C2.2 and C2.1) and generate >> a bunch of xdoc/apt files that will serve as a basis for managing a whole >> maven / svnsubpub based website (like as we're currently doing for C3); >> >> 3. use Apache CMS and try to import all existing documentation (including >> C3's, in this case) - as suggested by David in the e-mail below; >> >> I am for (2) and can spend some time for this, with some other volunteer, of >> course ;-) >> >> WDYT? >> Regards. >> >> On 16/01/2012 14:21, David Crossley wrote: >>> TL;DNR >>> Use the Apache CMS for at least our top-level docs >>> and the stalled 2.1 and 2.2 docs. >>> >>> >>> However, i cannot actually do this work, just explain and guide. >>> >>> I have done some background research to try to gather the >>> various past threads and docs. Perhaps this will help us to >>> bring the Cocoon documentation back to life. >>> >>> In the past we had the sources for the docs in xml format >>> and then processed by Apache Forrest to generate the html pages. >>> >>> A few years ago we moved to using the Daisy CMS to store/edit >>> all content for 2.1 and 2.2 versions, as well as the top-level >>> project non-version-specific stuff. >>> >>> For Cocoon-2.2, and the top-level stuff, the Maven site plugin >>> extracted the content
RE: Website management [WAS Re: resurrect the Cocoon documentation]
I am also for (2) although I can't promis much help. I think moving the docs to a CMS was one of the big mis-decisions of C2. The wishful thinking was that non-developers would come forward to improve the documentation which were before discouraged by the xdoc and svn. Sad reality was that the CMS created an extra threshold for any documentation update that it almost completely stopped. We should come back to where code and doc changes can be committed and published together. One major improvement over the past scheme would be if doc changes could be previewed live without a build cycle. Cheers, Alfred. -Original Message- From: Francesco Chicchiriccò [mailto:ilgro...@apache.org] Sent: Freitag, 16. März 2012 10:46 To: dev@cocoon.apache.org Subject: Website management [WAS Re: resurrect the Cocoon documentation] Hi all, yesterday, while looking at cocoon.zones.apache.org, I've spent some time at our website, and the e-mail below came into my mind. I believe we should act in this respect as soon as possible, since our outdated website is all but attractive and informative: think only that every page reports "Errors and Improvements? If you see any errors or potential improvements in this document please help us: View, Edit or comment on the latest development version (registration required)." pointing to a non-existing Daisy instance. Taking the attached e-mail into account, I think we should choose whether: 1. try to resurrect a Daisy instance in our jail - with Betrand's help / manage somehow 2.1 docs with forrest; 2. use Cocoon to parse existing HTML files (for C2.2 and C2.1) and generate a bunch of xdoc/apt files that will serve as a basis for managing a whole maven / svnsubpub based website (like as we're currently doing for C3); 3. use Apache CMS and try to import all existing documentation (including C3's, in this case) - as suggested by David in the e-mail below; I am for (2) and can spend some time for this, with some other volunteer, of course ;-) WDYT? Regards. On 16/01/2012 14:21, David Crossley wrote: > TL;DNR > Use the Apache CMS for at least our top-level docs > and the stalled 2.1 and 2.2 docs. > > > However, i cannot actually do this work, just explain and guide. > > I have done some background research to try to gather the > various past threads and docs. Perhaps this will help us to > bring the Cocoon documentation back to life. > > In the past we had the sources for the docs in xml format > and then processed by Apache Forrest to generate the html pages. > > A few years ago we moved to using the Daisy CMS to store/edit > all content for 2.1 and 2.2 versions, as well as the top-level > project non-version-specific stuff. > > For Cocoon-2.2, and the top-level stuff, the Maven site plugin > extracted the content from Daisy and generated the html pages. [4] > > For Cocoon-2.1, the Forrest plugin "Daisy input plugin" extracted > the content from Daisy and generated the html pages. [5] > > For Cocoon-3, the source content is stored in xml files > and the Maven site plugin generates the html pages. > > All generated html was (and still is) committed to the > Cocoon "site" SVN [1]. > > Then 'svn up' on the people.apache.org machine does the > publishing step. (Later that step could move to using svnpubsub.) > > The Daisy server operated on our Zones machine cocoon.zones.apache.org > (which also housed the demonstrations for Cocoon 2.1 and 2.2). > The Zones server is managed by the Cocoon project. See [2]. > > However, the machine that provided the zones for a set of > projects needed to be upgraded. The Cocoon project did not > move our services in time. > IIRC we do now have a "freebsd jail" which is basically configured, > but not yet re-installed Daisy or Cocoon demo examples, > nor the web server. > IIRC we did get a backup of the Daisy data [3] if that helps. > > The Forrest forrestbot neededi to be turned off, as it could not > access the source content for the 2.1 documentation. > > For the 2.2 documentation, i presume that Maven also has troubles. > > So unless someone can re-instate the new cocoon.zones.apache.org > and the Daisy server, then we need some other solution. > > Suggestion to use the Apache CMS: > > One other solution would be to use the new Apache CMS. [7] > > It can have source content in either Markdown format > or in HTML format and perhaps others. > > To resurrect the content, we might be able to use the > last published "generated" set of html documents, strip off > the outer headers and menu stuff, replace with basic header, > and use that set of content to seed the CMS. > > > (Some of these resources are only available to Cocoo
Re: Website management [WAS Re: resurrect the Cocoon documentation]
+1 for option #2, I like keeping the doc under control and in a format can be deployed wherever :) For that purpose, I just launched the VOTE thread for the Thien Skin 1.0.1. Thanks for leading this, all the best! -Simo http://people.apache.org/~simonetripodi/ http://simonetripodi.livejournal.com/ http://twitter.com/simonetripodi http://www.99soft.org/ 2012/3/16 Francesco Chicchiriccò : > Hi all, > yesterday, while looking at cocoon.zones.apache.org, I've spent some time at > our website, and the e-mail below came into my mind. > > I believe we should act in this respect as soon as possible, since our > outdated website is all but attractive and informative: think only that > every page reports "Errors and Improvements? If you see any errors or > potential improvements in this document please help us: View, Edit or > comment on the latest development version (registration required)." pointing > to a non-existing Daisy instance. > > Taking the attached e-mail into account, I think we should choose whether: > > 1. try to resurrect a Daisy instance in our jail - with Betrand's help / > manage somehow 2.1 docs with forrest; > > 2. use Cocoon to parse existing HTML files (for C2.2 and C2.1) and generate > a bunch of xdoc/apt files that will serve as a basis for managing a whole > maven / svnsubpub based website (like as we're currently doing for C3); > > 3. use Apache CMS and try to import all existing documentation (including > C3's, in this case) - as suggested by David in the e-mail below; > > I am for (2) and can spend some time for this, with some other volunteer, of > course ;-) > > WDYT? > Regards. > > On 16/01/2012 14:21, David Crossley wrote: >> >> TL;DNR >> Use the Apache CMS for at least our top-level docs >> and the stalled 2.1 and 2.2 docs. >> >> >> However, i cannot actually do this work, just explain and guide. >> >> I have done some background research to try to gather the >> various past threads and docs. Perhaps this will help us to >> bring the Cocoon documentation back to life. >> >> In the past we had the sources for the docs in xml format >> and then processed by Apache Forrest to generate the html pages. >> >> A few years ago we moved to using the Daisy CMS to store/edit >> all content for 2.1 and 2.2 versions, as well as the top-level >> project non-version-specific stuff. >> >> For Cocoon-2.2, and the top-level stuff, the Maven site plugin >> extracted the content from Daisy and generated the html pages. [4] >> >> For Cocoon-2.1, the Forrest plugin "Daisy input plugin" extracted >> the content from Daisy and generated the html pages. [5] >> >> For Cocoon-3, the source content is stored in xml files >> and the Maven site plugin generates the html pages. >> >> All generated html was (and still is) committed to the >> Cocoon "site" SVN [1]. >> >> Then 'svn up' on the people.apache.org machine does the >> publishing step. (Later that step could move to using svnpubsub.) >> >> The Daisy server operated on our Zones machine cocoon.zones.apache.org >> (which also housed the demonstrations for Cocoon 2.1 and 2.2). >> The Zones server is managed by the Cocoon project. See [2]. >> >> However, the machine that provided the zones for a set of >> projects needed to be upgraded. The Cocoon project did not >> move our services in time. >> IIRC we do now have a "freebsd jail" which is basically configured, >> but not yet re-installed Daisy or Cocoon demo examples, >> nor the web server. >> IIRC we did get a backup of the Daisy data [3] if that helps. >> >> The Forrest forrestbot neededi to be turned off, as it could not >> access the source content for the 2.1 documentation. >> >> For the 2.2 documentation, i presume that Maven also has troubles. >> >> So unless someone can re-instate the new cocoon.zones.apache.org >> and the Daisy server, then we need some other solution. >> >> Suggestion to use the Apache CMS: >> >> One other solution would be to use the new Apache CMS. [7] >> >> It can have source content in either Markdown format >> or in HTML format and perhaps others. >> >> To resurrect the content, we might be able to use the >> last published "generated" set of html documents, strip off >> the outer headers and menu stuff, replace with basic header, >> and use that set of content to seed the CMS. >> >> >> (Some of these resources are only available to Cocoon PMC members.) >> >>
Website management [WAS Re: resurrect the Cocoon documentation]
Hi all, yesterday, while looking at cocoon.zones.apache.org, I've spent some time at our website, and the e-mail below came into my mind. I believe we should act in this respect as soon as possible, since our outdated website is all but attractive and informative: think only that every page reports "Errors and Improvements? If you see any errors or potential improvements in this document please help us: View, Edit or comment on the latest development version (registration required)." pointing to a non-existing Daisy instance. Taking the attached e-mail into account, I think we should choose whether: 1. try to resurrect a Daisy instance in our jail - with Betrand's help / manage somehow 2.1 docs with forrest; 2. use Cocoon to parse existing HTML files (for C2.2 and C2.1) and generate a bunch of xdoc/apt files that will serve as a basis for managing a whole maven / svnsubpub based website (like as we're currently doing for C3); 3. use Apache CMS and try to import all existing documentation (including C3's, in this case) - as suggested by David in the e-mail below; I am for (2) and can spend some time for this, with some other volunteer, of course ;-) WDYT? Regards. On 16/01/2012 14:21, David Crossley wrote: TL;DNR Use the Apache CMS for at least our top-level docs and the stalled 2.1 and 2.2 docs. However, i cannot actually do this work, just explain and guide. I have done some background research to try to gather the various past threads and docs. Perhaps this will help us to bring the Cocoon documentation back to life. In the past we had the sources for the docs in xml format and then processed by Apache Forrest to generate the html pages. A few years ago we moved to using the Daisy CMS to store/edit all content for 2.1 and 2.2 versions, as well as the top-level project non-version-specific stuff. For Cocoon-2.2, and the top-level stuff, the Maven site plugin extracted the content from Daisy and generated the html pages. [4] For Cocoon-2.1, the Forrest plugin "Daisy input plugin" extracted the content from Daisy and generated the html pages. [5] For Cocoon-3, the source content is stored in xml files and the Maven site plugin generates the html pages. All generated html was (and still is) committed to the Cocoon "site" SVN [1]. Then 'svn up' on the people.apache.org machine does the publishing step. (Later that step could move to using svnpubsub.) The Daisy server operated on our Zones machine cocoon.zones.apache.org (which also housed the demonstrations for Cocoon 2.1 and 2.2). The Zones server is managed by the Cocoon project. See [2]. However, the machine that provided the zones for a set of projects needed to be upgraded. The Cocoon project did not move our services in time. IIRC we do now have a "freebsd jail" which is basically configured, but not yet re-installed Daisy or Cocoon demo examples, nor the web server. IIRC we did get a backup of the Daisy data [3] if that helps. The Forrest forrestbot neededi to be turned off, as it could not access the source content for the 2.1 documentation. For the 2.2 documentation, i presume that Maven also has troubles. So unless someone can re-instate the new cocoon.zones.apache.org and the Daisy server, then we need some other solution. Suggestion to use the Apache CMS: One other solution would be to use the new Apache CMS. [7] It can have source content in either Markdown format or in HTML format and perhaps others. To resurrect the content, we might be able to use the last published "generated" set of html documents, strip off the outer headers and menu stuff, replace with basic header, and use that set of content to seed the CMS. (Some of these resources are only available to Cocoon PMC members.) [1] http://svn.apache.org/repos/asf/cocoon/site/site/ [2] https://svn.apache.org/repos/private/pmc/cocoon/cocoon.zones.apache.org/ [3] Search the PMC archive for various email from Bertrand [4] http://cocoon.apache.org/1418_1_1.html How to publish docs to cocoon.apache.org (i.e. for Cocoon-2.2 and the top-level of c.a.o) [5] http://wiki.apache.org/cocoon/CocoonWebsiteUpdate How to publish Cocoon-2.1 docs [7] Apache CMS http://wiki.apache.org/general/ApacheCms2010 http://wiki.apache.org/general/ApacheCMSFAQ http://www.apache.org/dev/cmsref.html -- Francesco Chicchiriccò Apache Cocoon PMC and Apache Syncope PPMC Member http://people.apache.org/~ilgrosso/
resurrect the Cocoon documentation
TL;DNR Use the Apache CMS for at least our top-level docs and the stalled 2.1 and 2.2 docs. However, i cannot actually do this work, just explain and guide. I have done some background research to try to gather the various past threads and docs. Perhaps this will help us to bring the Cocoon documentation back to life. In the past we had the sources for the docs in xml format and then processed by Apache Forrest to generate the html pages. A few years ago we moved to using the Daisy CMS to store/edit all content for 2.1 and 2.2 versions, as well as the top-level project non-version-specific stuff. For Cocoon-2.2, and the top-level stuff, the Maven site plugin extracted the content from Daisy and generated the html pages. [4] For Cocoon-2.1, the Forrest plugin "Daisy input plugin" extracted the content from Daisy and generated the html pages. [5] For Cocoon-3, the source content is stored in xml files and the Maven site plugin generates the html pages. All generated html was (and still is) committed to the Cocoon "site" SVN [1]. Then 'svn up' on the people.apache.org machine does the publishing step. (Later that step could move to using svnpubsub.) The Daisy server operated on our Zones machine cocoon.zones.apache.org (which also housed the demonstrations for Cocoon 2.1 and 2.2). The Zones server is managed by the Cocoon project. See [2]. However, the machine that provided the zones for a set of projects needed to be upgraded. The Cocoon project did not move our services in time. IIRC we do now have a "freebsd jail" which is basically configured, but not yet re-installed Daisy or Cocoon demo examples, nor the web server. IIRC we did get a backup of the Daisy data [3] if that helps. The Forrest forrestbot neededi to be turned off, as it could not access the source content for the 2.1 documentation. For the 2.2 documentation, i presume that Maven also has troubles. So unless someone can re-instate the new cocoon.zones.apache.org and the Daisy server, then we need some other solution. Suggestion to use the Apache CMS: One other solution would be to use the new Apache CMS. [7] It can have source content in either Markdown format or in HTML format and perhaps others. To resurrect the content, we might be able to use the last published "generated" set of html documents, strip off the outer headers and menu stuff, replace with basic header, and use that set of content to seed the CMS. (Some of these resources are only available to Cocoon PMC members.) [1] http://svn.apache.org/repos/asf/cocoon/site/site/ [2] http://svn.apache.org/repos/private/pmc/cocoon/cocoon.zones.apache.org/ [3] Search the PMC archive for various email from Bertrand [4] http://cocoon.apache.org/1418_1_1.html How to publish docs to cocoon.apache.org (i.e. for Cocoon-2.2 and the top-level of c.a.o) [5] http://wiki.apache.org/cocoon/CocoonWebsiteUpdate How to publish Cocoon-2.1 docs [7] Apache CMS http://wiki.apache.org/general/ApacheCms2010 http://wiki.apache.org/general/ApacheCMSFAQ http://www.apache.org/dev/cmsref.html
Re: Cocoon documentation
Thorsten Scherler wrote: > On Fri, 2009-12-04 at 12:09 +0100, Reinhard Pötz wrote: > ... >> See >> http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/ >> >> You can generate the documentation yourself by invoking 'mvn site' from >> the base directory of the cocoon-docs module. > > I tried that but I get: > ... > [INFO] Unable to find resource > 'org.apache.cocoon:cocoon-thien-maven-site-skin:jar:1.0.0-SNAPSHOT' in > repository apache.snapshots > (http://people.apache.org/repo/m2-snapshot-repository) > [INFO] > > [ERROR] BUILD FAILURE > [INFO] > > [INFO] The skin does not exist: Unable to download the artifact from any > repository > > How can I fix this? Cocoon 2.2 trunk contains the cocoon-thien-maven-site-skin (http://svn.apache.org/repos/asf/cocoon/trunk/site/cocoon-thien-maven-site-skin/pom.xml). Either your build (mvn install) the complete Cocoon 2.2 trunk or you only build (mvn install) the parent POM and the site skin. I will also release the site skin so that it is available at the central Maven 2 repo. -- Reinhard Pötz Managing Director, {Indoqa} GmbH http://www.indoqa.com/en/people/reinhard.poetz/ Member of the Apache Software Foundation Apache Cocoon Committer, PMC member reinh...@apache.org
Re: Cocoon documentation
On Fri, 2009-12-04 at 12:09 +0100, Reinhard Pötz wrote: ... > See > http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/ > > You can generate the documentation yourself by invoking 'mvn site' from > the base directory of the cocoon-docs module. I tried that but I get: ... [INFO] Unable to find resource 'org.apache.cocoon:cocoon-thien-maven-site-skin:jar:1.0.0-SNAPSHOT' in repository apache.snapshots (http://people.apache.org/repo/m2-snapshot-repository) [INFO] [ERROR] BUILD FAILURE [INFO] [INFO] The skin does not exist: Unable to download the artifact from any repository How can I fix this? salu2 -- Thorsten Scherler Open Source Java Sociedad Andaluza para el Desarrollo de la Sociedad de la Información, S.A.U. (SADESI)
Re: Cocoon documentation
Jos Snellings wrote: > What editor do you use?. > (I mostly use XMLMind) yes, either XMLMind or I use use a schema-aware editor. -- Reinhard Pötz Managing Director, {Indoqa} GmbH http://www.indoqa.com/en/people/reinhard.poetz/ Member of the Apache Software Foundation Apache Cocoon Committer, PMC member reinh...@apache.org
Re: Cocoon documentation
What editor do you use?. (I mostly use XMLMind) On Fri, 2009-12-04 at 12:09 +0100, Reinhard Pötz wrote: > Jos Snellings wrote: > > Currently there is an initialisation problem. > > Anyway, Reinhard, you had a great table of contents. That is a good way > > to get started: what nodes are missing? That way, we may fill in the > > gaps, whilst trying our best to preserve unity of presentation & writing > > style > > All docbook, I guess? > > Yes, cocoon-docs is based on docbook and a Maven 2 docbook plugin that > creates html and pdf docs: > > See > http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/ > > You can generate the documentation yourself by invoking 'mvn site' from > the base directory of the cocoon-docs module. >
Re: Cocoon documentation
Jos Snellings wrote: > Currently there is an initialisation problem. > Anyway, Reinhard, you had a great table of contents. That is a good way > to get started: what nodes are missing? That way, we may fill in the > gaps, whilst trying our best to preserve unity of presentation & writing > style > All docbook, I guess? Yes, cocoon-docs is based on docbook and a Maven 2 docbook plugin that creates html and pdf docs: See http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/ You can generate the documentation yourself by invoking 'mvn site' from the base directory of the cocoon-docs module. -- Reinhard Pötz Managing Director, {Indoqa} GmbH http://www.indoqa.com/en/people/reinhard.poetz/ Member of the Apache Software Foundation Apache Cocoon Committer, PMC member reinh...@apache.org
Re: Cocoon documentation
Currently there is an initialisation problem. Anyway, Reinhard, you had a great table of contents. That is a good way to get started: what nodes are missing? That way, we may fill in the gaps, whilst trying our best to preserve unity of presentation & writing style All docbook, I guess? Jos On Fri, 2009-12-04 at 10:15 +0100, Reinhard Pötz wrote: > Matt Whipple wrote: > > Reinhard Pötz wrote: > >> Matt Whipple wrote: > >> > >>> Jos Snellings wrote: > >>> > The documentation of cocoon-3 can be checked out as: > svn co http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs\ > > > >>> I stumbled upon the HTML deliverable of that on > >>> http://people.apache.org/~reinhard/c3-ref/html/ after sending my email. > >>> I'd think it would be best if the official documentation focused on > >>> being primarily a comprehensive reference with a quick bootstrap guide. > >>> A community documentation site could then supplement that with all the > >>> typical tutorials/how-to's and tips & tricks which gets the reader where > >>> he wants to be with a straightforward, minimalist approach which then > >>> references the official docs and other more enlightening sources. > >>> Regular articles/blog entries could then highlight the activity in the > >>> community, and the possibilities of various Cocoon components could be > >>> showcased. Guides to all of the overlapping processes which can be > >>> [easily] extrapolated from existing material can be given a home so that > >>> a potential new developer with a specific need is provided with an > >>> apparent foot in the door. Basically a site which presents a welcoming, > >>> active community rather than seemingly a group of scattered people > >>> developing in Cocoons and enabling me to make bad wordplay (such is the > >>> price). To that end, an agreed upon forum would be ideal. > >>> > >> Agreed. When I started to write the C3 documentation, I had the Spring > >> reference documentation in mind. I think it's one of the best examples > >> because it focuses on describing the technology and the concepts. > >> > >> As a forum for everything beyond reference docs we could either use > >> Daisy or the Apache Wiki. (http://wiki.apache.org/cocoon) > >> > >> > > My thought would be Daisy (cocoondev.org?) so the site itself can be > > Cocoon powered and then the wiki can remain legacy docs. > > The Cocoon project runs its own Daisy instance at > http://cocoon.zones.apache.org/daisy/ > > We could setup a Cocoon 3 wiki site there. >
Re: Cocoon documentation
Matt Whipple wrote: > Reinhard Pötz wrote: >> Matt Whipple wrote: >> >>> Jos Snellings wrote: >>> The documentation of cocoon-3 can be checked out as: svn co http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs\ >>> I stumbled upon the HTML deliverable of that on >>> http://people.apache.org/~reinhard/c3-ref/html/ after sending my email. >>> I'd think it would be best if the official documentation focused on >>> being primarily a comprehensive reference with a quick bootstrap guide. >>> A community documentation site could then supplement that with all the >>> typical tutorials/how-to's and tips & tricks which gets the reader where >>> he wants to be with a straightforward, minimalist approach which then >>> references the official docs and other more enlightening sources. >>> Regular articles/blog entries could then highlight the activity in the >>> community, and the possibilities of various Cocoon components could be >>> showcased. Guides to all of the overlapping processes which can be >>> [easily] extrapolated from existing material can be given a home so that >>> a potential new developer with a specific need is provided with an >>> apparent foot in the door. Basically a site which presents a welcoming, >>> active community rather than seemingly a group of scattered people >>> developing in Cocoons and enabling me to make bad wordplay (such is the >>> price). To that end, an agreed upon forum would be ideal. >>> >> Agreed. When I started to write the C3 documentation, I had the Spring >> reference documentation in mind. I think it's one of the best examples >> because it focuses on describing the technology and the concepts. >> >> As a forum for everything beyond reference docs we could either use >> Daisy or the Apache Wiki. (http://wiki.apache.org/cocoon) >> >> > My thought would be Daisy (cocoondev.org?) so the site itself can be > Cocoon powered and then the wiki can remain legacy docs. The Cocoon project runs its own Daisy instance at http://cocoon.zones.apache.org/daisy/ We could setup a Cocoon 3 wiki site there. -- Reinhard Pötz Managing Director, {Indoqa} GmbH http://www.indoqa.com/en/people/reinhard.poetz/ Member of the Apache Software Foundation Apache Cocoon Committer, PMC member reinh...@apache.org
Re: Cocoon documentation
Reinhard Pötz wrote: > Matt Whipple wrote: > >> Jos Snellings wrote: >> >>> The documentation of cocoon-3 can be checked out as: >>> svn co http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs\ >>> >>> >> I stumbled upon the HTML deliverable of that on >> http://people.apache.org/~reinhard/c3-ref/html/ after sending my email. >> I'd think it would be best if the official documentation focused on >> being primarily a comprehensive reference with a quick bootstrap guide. >> A community documentation site could then supplement that with all the >> typical tutorials/how-to's and tips & tricks which gets the reader where >> he wants to be with a straightforward, minimalist approach which then >> references the official docs and other more enlightening sources. >> Regular articles/blog entries could then highlight the activity in the >> community, and the possibilities of various Cocoon components could be >> showcased. Guides to all of the overlapping processes which can be >> [easily] extrapolated from existing material can be given a home so that >> a potential new developer with a specific need is provided with an >> apparent foot in the door. Basically a site which presents a welcoming, >> active community rather than seemingly a group of scattered people >> developing in Cocoons and enabling me to make bad wordplay (such is the >> price). To that end, an agreed upon forum would be ideal. >> > > Agreed. When I started to write the C3 documentation, I had the Spring > reference documentation in mind. I think it's one of the best examples > because it focuses on describing the technology and the concepts. > > As a forum for everything beyond reference docs we could either use > Daisy or the Apache Wiki. (http://wiki.apache.org/cocoon) > > My thought would be Daisy (cocoondev.org?) so the site itself can be Cocoon powered and then the wiki can remain legacy docs.
Re: Cocoon documentation
Matt Whipple wrote: > Jos Snellings wrote: >> The documentation of cocoon-3 can be checked out as: >> svn co http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs\ >> > I stumbled upon the HTML deliverable of that on > http://people.apache.org/~reinhard/c3-ref/html/ after sending my email. > I'd think it would be best if the official documentation focused on > being primarily a comprehensive reference with a quick bootstrap guide. > A community documentation site could then supplement that with all the > typical tutorials/how-to's and tips & tricks which gets the reader where > he wants to be with a straightforward, minimalist approach which then > references the official docs and other more enlightening sources. > Regular articles/blog entries could then highlight the activity in the > community, and the possibilities of various Cocoon components could be > showcased. Guides to all of the overlapping processes which can be > [easily] extrapolated from existing material can be given a home so that > a potential new developer with a specific need is provided with an > apparent foot in the door. Basically a site which presents a welcoming, > active community rather than seemingly a group of scattered people > developing in Cocoons and enabling me to make bad wordplay (such is the > price). To that end, an agreed upon forum would be ideal. Agreed. When I started to write the C3 documentation, I had the Spring reference documentation in mind. I think it's one of the best examples because it focuses on describing the technology and the concepts. As a forum for everything beyond reference docs we could either use Daisy or the Apache Wiki. (http://wiki.apache.org/cocoon) -- Reinhard Pötz Managing Director, {Indoqa} GmbH http://www.indoqa.com/en/people/reinhard.poetz/ Member of the Apache Software Foundation Apache Cocoon Committer, PMC member reinh...@apache.org
Re: Cocoon documentation
Yes, that would be it... agreed. On Tue, 2009-12-01 at 06:23 -0500, Matt Whipple wrote: > Jos Snellings wrote: > > The documentation of cocoon-3 can be checked out as: > > svn co http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs\ > > > I stumbled upon the HTML deliverable of that on > http://people.apache.org/~reinhard/c3-ref/html/ after sending my email. > I'd think it would be best if the official documentation focused on > being primarily a comprehensive reference with a quick bootstrap guide. > A community documentation site could then supplement that with all the > typical tutorials/how-to's and tips & tricks which gets the reader where > he wants to be with a straightforward, minimalist approach which then > references the official docs and other more enlightening sources. > Regular articles/blog entries could then highlight the activity in the > community, and the possibilities of various Cocoon components could be > showcased. Guides to all of the overlapping processes which can be > [easily] extrapolated from existing material can be given a home so that > a potential new developer with a specific need is provided with an > apparent foot in the door. Basically a site which presents a welcoming, > active community rather than seemingly a group of scattered people > developing in Cocoons and enabling me to make bad wordplay (such is the > price). To that end, an agreed upon forum would be ideal. > > The cocoon community will be delighted at some good documentation. > > Talking about community I fear such as an active community is to be > > reestablished, so I think we'd better provide some sweet stuff. > > > > What would Reinhard think of starting with as a table of contents? > > I will be glad to write some documentation as well. I have some goose > > feathers available after Christmas, when I will be through the > > experience of creating a first > > How about you? > > Jos > > > > > > On Mon, 2009-11-30 at 08:07 -0500, Matt Whipple wrote: > > > >> I'm a recent transplant to Cocoon (and Java), in particular because > >> Cocoon 3 appears as though it is/will be closely in line with my own > >> perspective on web application development. I'm interested in > >> contributing to the development of the framework itself, but likely > >> won't be able to produce anything remotely useful for a couple months > >> as I familiarize myself with all of the related technologies. > >> > >> I've just read some of the attacks on the poor documentation of the > >> project and the resulting difficult entry for those unfamiliar. This > >> is, of course, easily confirmed by the combination of woefully out of > >> date references and dead links on the Web site (i.e. to the Daisy > >> site). As I am (obviously) hopeful to see Cocoon succeed, I certainly > >> don't want it to become mired in isolation like so many good projects. > >> > >> As such I'd like to try to contribute some documentation. Is there any > >> idea among the community as to where documentation should end up, or > >> should I just create a new site? Also, I'd lean towards focusing on > >> Cocoon 3, as having documentation in place for a new release would > >> likely have larger impact than attaching possibly overdue docs to an > >> older, in the process of being superseded one. This would be premature > >> if there's no foreseeable beta > >> > >> > > > > > > > >
Re: Cocoon documentation
Jos Snellings wrote: > The documentation of cocoon-3 can be checked out as: > svn co http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs\ > I stumbled upon the HTML deliverable of that on http://people.apache.org/~reinhard/c3-ref/html/ after sending my email. I'd think it would be best if the official documentation focused on being primarily a comprehensive reference with a quick bootstrap guide. A community documentation site could then supplement that with all the typical tutorials/how-to's and tips & tricks which gets the reader where he wants to be with a straightforward, minimalist approach which then references the official docs and other more enlightening sources. Regular articles/blog entries could then highlight the activity in the community, and the possibilities of various Cocoon components could be showcased. Guides to all of the overlapping processes which can be [easily] extrapolated from existing material can be given a home so that a potential new developer with a specific need is provided with an apparent foot in the door. Basically a site which presents a welcoming, active community rather than seemingly a group of scattered people developing in Cocoons and enabling me to make bad wordplay (such is the price). To that end, an agreed upon forum would be ideal. > The cocoon community will be delighted at some good documentation. > Talking about community I fear such as an active community is to be > reestablished, so I think we'd better provide some sweet stuff. > > What would Reinhard think of starting with as a table of contents? > I will be glad to write some documentation as well. I have some goose > feathers available after Christmas, when I will be through the > experience of creating a first > How about you? > Jos > > > On Mon, 2009-11-30 at 08:07 -0500, Matt Whipple wrote: > >> I'm a recent transplant to Cocoon (and Java), in particular because >> Cocoon 3 appears as though it is/will be closely in line with my own >> perspective on web application development. I'm interested in >> contributing to the development of the framework itself, but likely >> won't be able to produce anything remotely useful for a couple months >> as I familiarize myself with all of the related technologies. >> >> I've just read some of the attacks on the poor documentation of the >> project and the resulting difficult entry for those unfamiliar. This >> is, of course, easily confirmed by the combination of woefully out of >> date references and dead links on the Web site (i.e. to the Daisy >> site). As I am (obviously) hopeful to see Cocoon succeed, I certainly >> don't want it to become mired in isolation like so many good projects. >> >> As such I'd like to try to contribute some documentation. Is there any >> idea among the community as to where documentation should end up, or >> should I just create a new site? Also, I'd lean towards focusing on >> Cocoon 3, as having documentation in place for a new release would >> likely have larger impact than attaching possibly overdue docs to an >> older, in the process of being superseded one. This would be premature >> if there's no foreseeable beta >> >> > > >
Re: Cocoon documentation
The documentation of cocoon-3 can be checked out as: svn co http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs The cocoon community will be delighted at some good documentation. Talking about community I fear such as an active community is to be reestablished, so I think we'd better provide some sweet stuff. What would Reinhard think of starting with as a table of contents? I will be glad to write some documentation as well. I have some goose feathers available after Christmas, when I will be through the experience of creating a first app. How about you? Jos On Mon, 2009-11-30 at 08:07 -0500, Matt Whipple wrote: > I'm a recent transplant to Cocoon (and Java), in particular because > Cocoon 3 appears as though it is/will be closely in line with my own > perspective on web application development. I'm interested in > contributing to the development of the framework itself, but likely > won't be able to produce anything remotely useful for a couple months > as I familiarize myself with all of the related technologies. > > I've just read some of the attacks on the poor documentation of the > project and the resulting difficult entry for those unfamiliar. This > is, of course, easily confirmed by the combination of woefully out of > date references and dead links on the Web site (i.e. to the Daisy > site). As I am (obviously) hopeful to see Cocoon succeed, I certainly > don't want it to become mired in isolation like so many good projects. > > As such I'd like to try to contribute some documentation. Is there any > idea among the community as to where documentation should end up, or > should I just create a new site? Also, I'd lean towards focusing on > Cocoon 3, as having documentation in place for a new release would > likely have larger impact than attaching possibly overdue docs to an > older, in the process of being superseded one. This would be premature > if there's no foreseeable beta >
Cocoon documentation
I'm a recent transplant to Cocoon (and Java), in particular because Cocoon 3 appears as though it is/will be closely in line with my own perspective on web application development. I'm interested in contributing to the development of the framework itself, but likely won't be able to produce anything remotely useful for a couple months as I familiarize myself with all of the related technologies. I've just read some of the attacks on the poor documentation of the project and the resulting difficult entry for those unfamiliar. This is, of course, easily confirmed by the combination of woefully out of date references and dead links on the Web site (i.e. to the Daisy site). As I am (obviously) hopeful to see Cocoon succeed, I certainly don't want it to become mired in isolation like so many good projects. As such I'd like to try to contribute some documentation. Is there any idea among the community as to where documentation should end up, or should I just create a new site? Also, I'd lean towards focusing on Cocoon 3, as having documentation in place for a new release would likely have larger impact than attaching possibly overdue docs to an older, in the process of being superseded one. This would be premature if there's no foreseeable beta
Re: editing rights Cocoon documentation for user account robbypelssers
Robby Pelssers wrote: > > My ICLA has just been sent to secret...@apache.org. > > Happy to contribute, > Robby Thanks, i see that it is now recorded in SVN. -David
RE: editing rights Cocoon documentation for user account robbypelssers
@David My ICLA has just been sent to secret...@apache.org. Happy to contribute, Robby -Original Message- From: David Crossley [mailto:cross...@apache.org] Sent: Friday, September 18, 2009 5:10 AM To: dev@cocoon.apache.org Subject: Re: editing rights Cocoon documentation for user account robbypelssers Vadim Gritsenko wrote: > Robby Pelssers wrote: > > > >Can you grant editing rights to useraccount ?robbypelssers? for the > >cocoon documentation? > > Done Thanks for helping Cocoon, Robby. Would you please also send in a "Contributor License Agreement" http://apache.org/licenses/#clas -David
Re: editing rights Cocoon documentation for user account robbypelssers
Vadim Gritsenko wrote: > Robby Pelssers wrote: > > > >Can you grant editing rights to useraccount ?robbypelssers? for the > >cocoon documentation? > > Done Thanks for helping Cocoon, Robby. Would you please also send in a "Contributor License Agreement" http://apache.org/licenses/#clas -David
Re: editing rights Cocoon documentation for user account robbypelssers
On Sep 16, 2009, at 8:55 AM, Robby Pelssers wrote: Can you grant editing rights to useraccount ‘robbypelssers’ for the cocoon documentation? Done Vadim
editing rights Cocoon documentation for user account robbypelssers
Hi, Can you grant editing rights to useraccount 'robbypelssers' for the cocoon documentation? Cheers, Robby Pelssers
[jira] Closed: (COCOON-1680) New design/ layout proposal for Cocoon documentation
[ https://issues.apache.org/jira/browse/COCOON-1680?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ] Helma van der Linden closed COCOON-1680. Resolution: Won't Fix There is another redesign (COCOON-2043) implemented. > New design/ layout proposal for Cocoon documentation > > > Key: COCOON-1680 > URL: https://issues.apache.org/jira/browse/COCOON-1680 > Project: Cocoon > Issue Type: Improvement > Components: - Documentation >Reporter: Milan Andrejevic >Assignee: Cocoon Developers Team >Priority: Minor > Attachments: asf20051107.zip, asf20051108.zip, screenshot.gif, > screenshot.gif > > > I made new design/ layout proposal for Cocoon documentation. Just one html > and screen css. I understand you need to "modernize" site (see Upayavira > comment for COCOON-1679). This is my try, I hope you like it. > There are two layouts user can choose. Layout info is stored in cookie > "_asfstyle" for 30 days. > Added access keys on top menu. > Navigation on right contains only sub-section selected form top menu > Minimal resolution set to 800px. > Starting design is done in Macromedia Fireworks (_src/cocoon.png) were you > can find all picture slices. > I have checked this design in: > Windows: > Firefox 1.0.7 > Internet Explorer 6.0 > Opera 8.5 > Linux: > Firefox 1.0.7 > Konqueror 3.3.2 > Mozilla 1.7.5 > Netscape 7.2 > Lynx -- This message is automatically generated by JIRA. - You can reply to this email to add a comment to the issue online.
[jira] Updated: (COCOON-1826) OSGi-based Cocoon documentation
[ https://issues.apache.org/jira/browse/COCOON-1826?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ] Grzegorz Kossakowski updated COCOON-1826: - Component/s: (was: - Servlet service framework) - OSGi integration > OSGi-based Cocoon documentation > --- > > Key: COCOON-1826 > URL: https://issues.apache.org/jira/browse/COCOON-1826 > Project: Cocoon > Issue Type: Task > Components: - OSGi integration >Reporter: Reinhard Poetz > > Container task for blocks-fw documentation -- This message is automatically generated by JIRA. - You can reply to this email to add a comment to the issue online.
Re: svn commit: r516147 - /cocoon/trunk/tools/sitemaptags2daisy/src/main/java/org/apache/cocoon/documentation/daisy/SitemapTagsToDaisy.java
[EMAIL PROTECTED] wrote: Author: bruno Date: Thu Mar 8 11:00:50 2007 New Revision: 516147 URL: http://svn.apache.org/viewvc?view=rev&rev=516147 Log: Modified the sitemaptags2daisy tool so that documents are added to a block-dependent collection ("cdocs-" + block name) instead of the fixed "documentation" collection. Also made it so that everything below "core" gets assigned to the block "core" (rather than pipeline, sitemap, ...) Thanks Bruno for your help! Now each module documentation can include "its" sitemap component documents by using a query, e.g. http://cocoon.zones.apache.org/daisy/cdocs-core/g9/Matcher/899.html. -- Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach {Software Engineering, Open Source, Web Applications, Apache Cocoon} web(log): http://www.poetz.cc
Re: The Cocoon documentation: a lot has happened here
Arje Cahn said the following on 6/11/06 16:29: News on the homepage: excellent!! I love it. It would be better if we could have the date presented as part of the title: # 10/18/06: News Management in our Docs submitted by Ross Gardler, 10/18/06 9:59:32 PM I tend to disagree on this, although in the "new and flashy" design I could have the date be displayed more prominently. Although this is fine with me, I got lost in the subsite-principle. I'd much rather have a single navigational structure for all parts. It took me a while before I noticed "Cocoon core" in the top navigation, clicked on it and got to something that looks like the same website, but has a completely different navigation. Maybe I've missed out on this discussion, but it makes it really hard for me to find things What is the reason for this? The current navigation is a mixture of navigation describing the new site and navigation for documentation committers. IIUC the parts below "Website Only" in the "core" site display the navigation that is shown on the site. The "Main Site" part is the top-level, i.e. the menu shown on the top left when you start with the site. The other parts (Core, Blocks, Maven plugins) are "tabs" on the top right in the light colored bar below the header. The "Site Overview" part is intended for a global navigation in Daisy. All other parts of this navigation contain information on documentation specific topics. All the subsites (below "core") are intended for the specific block. The navigation defined in that block is also included in the site. I fully agree that this setup is not very clear and straightforward. Still, I think this is the best trade off between a setup for an automatic website creation and a clear place to jump in to write block or core specific documentation. On a sidenote, if someone has a drawing of the Cocoon 2.1/2.2/3.0 architectures (sketch would be fine), I could get it redone by the guy who is currently redesigning Hippo's architectural diagrams. Same goes for the 'pipelined transformation' graphic. Could explain a lot if we would have that on the homepage! Great! Thanks for the offer. Now, is there anything we can do about the Wiki pages? There have always been quite a bunch of pages that on the Wiki that deserve to be moved into the documentation. Also, the Wiki used to have a very low entry barrier, it would be easier to use that as a sandbox and move finished docs into the documentation website. True, I've been moving obvious pages to Daisy already. However, I think we need to have a common agreement on the role of the wiki. E.g. if some user wants to write documentation, where should he/she be doing that? The wiki? Give them an account for Daisy? I know we've had a similar discussion about a year ago but nothing definitive came out of it. I think now is the time to make a decision. Bye, Helma
Re: The Cocoon documentation: a lot has happened here
Arje Cahn wrote: Hi Reinhard, Helma and others, A big thanks (again!) for your work on the documentation. With my sceptical hat on, I took a quick glimpse at http://cocoon.zones.apache.org/dev-docs/, and found myself actually pretty surprised by the refreshing new look. :) But I hope you don't mind if I add some (really trivial) suggestions.. I'm not going to dive into the quality of the content itself, since this is clearly a work in progress. But there's some small things about the structure. News on the homepage: excellent!! I love it. It would be better if we could have the date presented as part of the title: # 10/18/06: News Management in our Docs submitted by Ross Gardler, 10/18/06 9:59:32 PM We are experimenting with a news management system in our Daisy driven documentation system. Simply create a new document with the type "NewsEntry" ... [more] # 10/17/06: Cocoon GT 2006 in Amsterdam submitted by Reinhard, 10/17/06 9:59:32 PM The Apache Cocoon community is proud to announce the fifth (!) annual edition of the Cocoon GetTogether, the main annual ... [more] should be possible, will have a look at it. The 4 hour update schedule is more than enough for me. note that we can only automatize it completly for the preview version that is deployed to cocoon.zones.apache.org. For cocoon.apache.org we still have to check in our docs into SVN which requires a handful of manual steps. Still, I'd love to see some blogentries right there on the homepage as well... Just an aggregate of committer blogs that list only items categorized as 'Cocoon'. TBH, I don't have a good idea how to integrate this ... :-/ - Following the split up of Cocoon (the code) we also split up the documentation into much smaller pieces. The rule is that each deployment unit has it's own documentation. Although this is fine with me, I got lost in the subsite-principle. I'd much rather have a single navigational structure for all parts. It took me a while before I noticed "Cocoon core" in the top navigation, clicked on it and got to something that looks like the same website, but has a completely different navigation. Maybe I've missed out on this discussion, but it makes it really hard for me to find things What is the reason for this? IMHO the documentation for a deployment unit should be able to stand alone. For me it's more confusing if a get a tree with hundreds of nodes. One of the goals of the new design should be a clear navigation that makes it obvious where to find what. - The documentation is automatically exported to http://cocoon.zones.apache.org/dev-docs/ every 4 hours. I noticed that this website is horribly slow... Got any clue why this happens? Currently it's pretty fast, but we don't have a guaranteed performance at the zones server. At http://cocoon.zones.apache.org/daisy/cdocs/1201.html you can find how-tos (about adding and publishing docs) and an overview of how the documentation system works. I guess the editing part should mimic the presentation from the published result? What do you mean with "editing part"? Helma will also work on a new flashy design for our site, though we both don't think that this effort should block publishing the docs using the "well-known" Maven skin as soon as the content is good enough. Does anybody disagree? I totally agree! Let's get things rolling first.. On a sidenote, if someone has a drawing of the Cocoon 2.1/2.2/3.0 architectures (sketch would be fine), I could get it redone by the guy who is currently redesigning Hippo's architectural diagrams. Same goes for the 'pipelined transformation' graphic. Could explain a lot if we would have that on the homepage! that would be great! As many people agreed that it is *very important* to have good documentation, Helma and I hope that others join us. Don't hesitate if you think that all this stuff is complicated. It's definitly not! Just go to http://cocoon.zones.apache.org/daisy/, choose the site that you want to improve and do it! Now, is there anything we can do about the Wiki pages? There have always been quite a bunch of pages that on the Wiki that deserve to be moved into the documentation. Also, the Wiki used to have a very low entry barrier, it would be easier to use that as a sandbox and move finished docs into the documentation website. yes, using Daisy as our wiki would be great but it needs somebody who drives this effort Thanks for picking this up! -- Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach {Software Engineering, Open Source, Web Applications, Apache Cocoon} web(log): http://www.poetz.cc ___ Telefonate ohne weitere K
RE: The Cocoon documentation: a lot has happened here
Hi Reinhard, Helma and others, A big thanks (again!) for your work on the documentation. With my sceptical hat on, I took a quick glimpse at http://cocoon.zones.apache.org/dev-docs/, and found myself actually pretty surprised by the refreshing new look. :) But I hope you don't mind if I add some (really trivial) suggestions.. I'm not going to dive into the quality of the content itself, since this is clearly a work in progress. But there's some small things about the structure. News on the homepage: excellent!! I love it. It would be better if we could have the date presented as part of the title: # 10/18/06: News Management in our Docs submitted by Ross Gardler, 10/18/06 9:59:32 PM We are experimenting with a news management system in our Daisy driven documentation system. Simply create a new document with the type "NewsEntry" ... [more] # 10/17/06: Cocoon GT 2006 in Amsterdam submitted by Reinhard, 10/17/06 9:59:32 PM The Apache Cocoon community is proud to announce the fifth (!) annual edition of the Cocoon GetTogether, the main annual ... [more] The 4 hour update schedule is more than enough for me. Still, I'd love to see some blogentries right there on the homepage as well... Just an aggregate of committer blogs that list only items categorized as 'Cocoon'. > - Following the split up of Cocoon (the code) we also split up the > documentation into much smaller pieces. The rule is that > each deployment > unit has it's own documentation. Although this is fine with me, I got lost in the subsite-principle. I'd much rather have a single navigational structure for all parts. It took me a while before I noticed "Cocoon core" in the top navigation, clicked on it and got to something that looks like the same website, but has a completely different navigation. Maybe I've missed out on this discussion, but it makes it really hard for me to find things What is the reason for this? > - The documentation is automatically exported to > http://cocoon.zones.apache.org/dev-docs/ every 4 hours. I noticed that this website is horribly slow... Got any clue why this happens? > At http://cocoon.zones.apache.org/daisy/cdocs/1201.html you > can find how-tos (about adding and publishing docs) and an > overview of how the documentation system works. I guess the editing part should mimic the presentation from the published result? > Helma will also work on a new flashy design for our site, > though we both don't think that this effort should block > publishing the docs using the "well-known" > Maven skin as soon as the content is good enough. Does > anybody disagree? I totally agree! Let's get things rolling first.. On a sidenote, if someone has a drawing of the Cocoon 2.1/2.2/3.0 architectures (sketch would be fine), I could get it redone by the guy who is currently redesigning Hippo's architectural diagrams. Same goes for the 'pipelined transformation' graphic. Could explain a lot if we would have that on the homepage! > As many people agreed that it is *very important* to have > good documentation, Helma and I hope that others join us. > Don't hesitate if you think that all this stuff is > complicated. It's definitly not! Just go to > http://cocoon.zones.apache.org/daisy/, choose the site that > you want to improve and do it! Now, is there anything we can do about the Wiki pages? There have always been quite a bunch of pages that on the Wiki that deserve to be moved into the documentation. Also, the Wiki used to have a very low entry barrier, it would be easier to use that as a sandbox and move finished docs into the documentation website. Thanks for picking this up! Arjé
Re: The Cocoon documentation: a lot has happened here
2006/11/5, Reinhard Poetz <[EMAIL PROTECTED]>: Andreas Hochsteger wrote: > May I get some karma to edit the docs in Daisy? > My username is 'ahochsteger'. done Thanks! Just trying to get familiar with Daisy now ... looks really good to me, BTW! -- Andreas
Re: The Cocoon documentation: a lot has happened here
Andreas Hochsteger wrote: May I get some karma to edit the docs in Daisy? My username is 'ahochsteger'. done -- Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach {Software Engineering, Open Source, Web Applications, Apache Cocoon} web(log): http://www.poetz.cc ___ Telefonate ohne weitere Kosten vom PC zum PC: http://messenger.yahoo.de
Re: The Cocoon documentation: a lot has happened here
2006/11/3, Reinhard Poetz <[EMAIL PROTECTED]>: 2 weeks ago, Arje posted a long list of things that need to be improved with our website and documentation. I can't say that all the things are resolved but Helma and I have made good progress: Thanks for your effort - it's really a big step forward! As many people agreed that it is *very important* to have good documentation, Helma and I hope that others join us. Don't hesitate if you think that all this stuff is complicated. It's definitly not! Just go to http://cocoon.zones.apache.org/daisy/, choose the site that you want to improve and do it! May I get some karma to edit the docs in Daisy? My username is 'ahochsteger'. Thanks, Andreas
Re: The Cocoon documentation: a lot has happened here
Reinhard Poetz wrote: > Carsten Ziegeler wrote: >> Great work! > > Thank you :-) > >> Is there any possibility to change the order of the navigation items, >> for example, if you look at: >> >> http://cocoon.zones.apache.org/dev-docs/core-modules/core/2.2/ >> >> The first main topic is about blocks and further down the list is the >> core. I think this should be the other way round, especially as the >> blocks stuff is not finished yet. > > Yes, it's the same order as in Daisy. Go to > http://cocoon.zones.apache.org/daisy/cdocs-core/, then click on [Go to > navigation document], and then select "Edit" from the "Page Actions" menu > item. > Thanks, that works - for some reason I didn't manage to change it some days ago. Carsten -- Carsten Ziegeler - Chief Architect http://www.s-und-n.de http://www.osoco.org/weblogs/rael/
Re: The Cocoon documentation: a lot has happened here
Carsten Ziegeler wrote: Great work! Thank you :-) Is there any possibility to change the order of the navigation items, for example, if you look at: http://cocoon.zones.apache.org/dev-docs/core-modules/core/2.2/ The first main topic is about blocks and further down the list is the core. I think this should be the other way round, especially as the blocks stuff is not finished yet. Yes, it's the same order as in Daisy. Go to http://cocoon.zones.apache.org/daisy/cdocs-core/, then click on [Go to navigation document], and then select "Edit" from the "Page Actions" menu item. -- Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach {Software Engineering, Open Source, Web Applications, Apache Cocoon} web(log): http://www.poetz.cc ___ Der frühe Vogel fängt den Wurm. Hier gelangen Sie zum neuen Yahoo! Mail: http://mail.yahoo.de
Re: The Cocoon documentation: a lot has happened here
Great work! Is there any possibility to change the order of the navigation items, for example, if you look at: http://cocoon.zones.apache.org/dev-docs/core-modules/core/2.2/ The first main topic is about blocks and further down the list is the core. I think this should be the other way round, especially as the blocks stuff is not finished yet. Carsten Reinhard Poetz wrote: > 2 weeks ago, Arje posted a long list of things that need to be improved with > our > website and documentation. I can't say that all the things are resolved but > Helma and I have made good progress: > > - Following the split up of Cocoon (the code) we also split up the > documentation into much smaller pieces. The rule is that each deployment > unit has it's own documentation. > > - Publishing our docs to cocoon.apache.org will be 4 steps that have to be > performed at the shell at cocoon.zones.apche.org (see > http://cocoon.zones.apache.org/daisy/cdocs/1201.html) Thanks Vadim for > your help with that! > > I think that's a good compromise between fast turn-around-cycles and > following the policy of having all our website content in SVN. > > - The Daisy Maven plugin is in place and is able to extract the content of > our CMS. > > - The documentation is automatically exported to > http://cocoon.zones.apache.org/dev-docs/ every 4 hours. > > This export can also be triggered off from the Continuum web app. > Go to http://cocoon.zones.apache.org:12000/continuum/servlet/continuum and > rebuild the "$cdcos" project. > > - Ross and I added news items to the homepage. As Ross explained, this list > is created dynamically by a query. > > At http://cocoon.zones.apache.org/daisy/cdocs/1201.html you can find how-tos > (about adding and publishing docs) and an overview of how the documentation > system works. > > - o - > > In my opinion the technical problems are mostly solved. The next step is > filling > the CMS with content. In particular we should focus on two sites > > - cdocs-main-site (http://cocoon.zones.apache.org/daisy/cdocs-site-main/) > - cdocs-core (http://cocoon.zones.apache.org/daisy/cdocs-core/) > > Then it's time to publish the new docs. WDYT? > > Of course, this shouldn't prevent you from working on the many other sites > (forms, template, flowscript etc.) if you think that your work is more > efficient > there. > > - o - > > Helma will also work on a new flashy design for our site, though we both > don't > think that this effort should block publishing the docs using the > "well-known" > Maven skin as soon as the content is good enough. Does anybody disagree? > > - o - > > As many people agreed that it is *very important* to have good documentation, > Helma and I hope that others join us. Don't hesitate if you think that all > this > stuff is complicated. It's definitly not! Just go to > http://cocoon.zones.apache.org/daisy/, choose the site that you want to > improve > and do it! > -- Carsten Ziegeler - Chief Architect http://www.s-und-n.de http://www.osoco.org/weblogs/rael/
The Cocoon documentation: a lot has happened here
2 weeks ago, Arje posted a long list of things that need to be improved with our website and documentation. I can't say that all the things are resolved but Helma and I have made good progress: - Following the split up of Cocoon (the code) we also split up the documentation into much smaller pieces. The rule is that each deployment unit has it's own documentation. - Publishing our docs to cocoon.apache.org will be 4 steps that have to be performed at the shell at cocoon.zones.apche.org (see http://cocoon.zones.apache.org/daisy/cdocs/1201.html) Thanks Vadim for your help with that! I think that's a good compromise between fast turn-around-cycles and following the policy of having all our website content in SVN. - The Daisy Maven plugin is in place and is able to extract the content of our CMS. - The documentation is automatically exported to http://cocoon.zones.apache.org/dev-docs/ every 4 hours. This export can also be triggered off from the Continuum web app. Go to http://cocoon.zones.apache.org:12000/continuum/servlet/continuum and rebuild the "$cdcos" project. - Ross and I added news items to the homepage. As Ross explained, this list is created dynamically by a query. At http://cocoon.zones.apache.org/daisy/cdocs/1201.html you can find how-tos (about adding and publishing docs) and an overview of how the documentation system works. - o - In my opinion the technical problems are mostly solved. The next step is filling the CMS with content. In particular we should focus on two sites - cdocs-main-site (http://cocoon.zones.apache.org/daisy/cdocs-site-main/) - cdocs-core (http://cocoon.zones.apache.org/daisy/cdocs-core/) Then it's time to publish the new docs. WDYT? Of course, this shouldn't prevent you from working on the many other sites (forms, template, flowscript etc.) if you think that your work is more efficient there. - o - Helma will also work on a new flashy design for our site, though we both don't think that this effort should block publishing the docs using the "well-known" Maven skin as soon as the content is good enough. Does anybody disagree? - o - As many people agreed that it is *very important* to have good documentation, Helma and I hope that others join us. Don't hesitate if you think that all this stuff is complicated. It's definitly not! Just go to http://cocoon.zones.apache.org/daisy/, choose the site that you want to improve and do it! -- Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach {Software Engineering, Open Source, Web Applications, Apache Cocoon} web(log): http://www.poetz.cc ___ Telefonate ohne weitere Kosten vom PC zum PC: http://messenger.yahoo.de
[jira] Updated: (COCOON-1826) OSGi-based Cocoon documentation
[ http://issues.apache.org/jira/browse/COCOON-1826?page=all ] Reinhard Poetz updated COCOON-1826: --- Summary: OSGi-based Cocoon documentation (was: Documentation) use a more specific name > OSGi-based Cocoon documentation > --- > > Key: COCOON-1826 > URL: http://issues.apache.org/jira/browse/COCOON-1826 > Project: Cocoon > Type: Task > Components: - Blocks Framework > Reporter: Reinhard Poetz > > Container task for blocks-fw documentation -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
Re: Use Maven 2 for the generation of the Cocoon documentation
On Tue, 2006-03-07 at 09:06 +0100, Reinhard Poetz wrote: > Bruno Dumon wrote: > > > OTOH, having the docs > > split up between a lot of little maven-sites might lessen the overview. > > Because of the nature of Daisy this shouldn't become a problem: > > - we can have one navigation document which is a collection of all > block navigation docs > - we have Daisy books > - if that's not enough, we can refer to the same document from different > navigation docs Yes indeed, we can republish the same content in different ways. -- Bruno Dumon http://outerthought.org/ Outerthought - Open Source, Java & XML Competence Support Center [EMAIL PROTECTED] [EMAIL PROTECTED]
Re: Use Maven 2 for the generation of the Cocoon documentation
Bruno Dumon wrote: On Mon, 2006-03-06 at 18:39 +0100, Reinhard Poetz wrote: hepabolu wrote: Finally, adding the proposed plugin can always be added later without loosing the effort of the current setup. ok, that's right. Anyway, I can't do it myself now but if somebody is interested, I can help. Maybe some of the Daisy gurus here can comment on the idea itself? It shouldn't be too hard. If it is just for publishing, you don't even need the Daisy client libraries, being able to do a HTTP request is enough. Actually, I should correct my previous statement the Forrest plugin uses the http API not the Java client API. No need for the Java API at this stage. I'm not sure what the difficulties are that Ross refers too in reusing the navigation documents. A basic plugin can probably be created in a day (by an experienced Java/XSLT person). Actually, my comment was misleading, sorry. The "difficulties" are not with Daisy itself, rather with the fact that we need(e) to maintain the existing directory structures of the documents and the Daisy nav system didn't work in the same way as the old nav system. With the 2.2 docs there is no legacy structure to maintain so it will be much easier. Ross
Re: Use Maven 2 for the generation of the Cocoon documentation
Bruno Dumon wrote: OTOH, having the docs split up between a lot of little maven-sites might lessen the overview. Because of the nature of Daisy this shouldn't become a problem: - we can have one navigation document which is a collection of all block navigation docs - we have Daisy books - if that's not enough, we can refer to the same document from different navigation docs -- Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach {Software Engineering, Open Source, Web Applications, Apache Cocoon} web(log): http://www.poetz.cc ___ Telefonate ohne weitere Kosten vom PC zum PC: http://messenger.yahoo.de
Re: Use Maven 2 for the generation of the Cocoon documentation
On Mon, 2006-03-06 at 18:39 +0100, Reinhard Poetz wrote: > hepabolu wrote: > > > Finally, adding the proposed plugin can always be added later without > > loosing the effort of the current setup. > > ok, that's right. Anyway, I can't do it myself now but if somebody is > interested, I can help. Maybe some of the Daisy gurus here can comment on the > idea itself? > It shouldn't be too hard. If it is just for publishing, you don't even need the Daisy client libraries, being able to do a HTTP request is enough. I'm not sure what the difficulties are that Ross refers too in reusing the navigation documents. A basic plugin can probably be created in a day (by an experienced Java/XSLT person). As for publishing the docs via Maven, I can understand the benefits to that, especially as each block will become less dependent on the core and might be versioned and released independently. OTOH, having the docs split up between a lot of little maven-sites might lessen the overview. In the short term, personally I'll focus on the actual content, as I think that's a more urgent issue. However, while writing docs, we should keep in mind to keep the docs related to a block grouped, focussed and independent from each other, so that we don't make this proposal harder to achieve. [only slightly related to this thread...] Something which I'll look in setting up soon is to allow to refer to javadoc using a "javadoc:" URL which gets translated to the actual javadoc location during publishing. To make it more block-oriented, the syntax will probably be something like "javadoc::org/apache/...". -- Bruno Dumon http://outerthought.org/ Outerthought - Open Source, Java & XML Competence Support Center [EMAIL PROTECTED] [EMAIL PROTECTED]
Re: Use Maven 2 for the generation of the Cocoon documentation
Reinhard Poetz wrote: As written in my mail "Status of block development" (http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=114165989221631&w=2) I propose a change in the Cocoon documentation creation: We have put a lot of work into the Mavenization of the Cocoon build system. As you might know, Maven provides a site generation goal "site:site". This makes is very simple to integrate a lot of reports (javadocs, jdepend, cobertura, svn activities, ...) and uses information available in pom.xml to produce docs. IMO the only missing part is the integration of our docs that are managed by Daisy. My idea is: - write a Maven plugin that can access Daisy - it is configured by the doc-id of a navigation documentent which is the root of the block documentation - the plugin uses the Daisy client API to access this navigation doc and generates docs out of it by crawling all references docs and resources. The result of this process is added to the generated site. First, does this proposal make sense from a technical point of view? Is anybody interested in working on this? I can help with the Maven part of starting a Maven plugin project a bit. I have no experience of Maven so can make no comment on that end of things. Reusing the Daisy navigation documents is not a trivial task, but it is certanly possible. What you describe is exactly what the Forrest plugin does. An alternative approach, and one that I am keen to follow if my own time allows (not right now). Is to create a Maven plugin for Forrest, thus we would use the two tools to produce what they are best at. However, as I said, I do not have the time to do this right now. So if someone wants to go the maven plugin route then go for it. Ross
Re: Use Maven 2 for the generation of the Cocoon documentation
hepabolu schrieb: > Carsten Ziegeler said the following on 06-03-2006 17:49: >> I'm more than +1 for getting the reports Maven provides for us on our >> website. I'm not >> sure if we need a plugin for the daisy docs or if just linking from the >> maven generated site is enough. Whatever works best. > > Let's do this one step at a time and do Carsten's proposal first. I've > been experimenting with exactly this just after the Cocoon Gettogether, > but my Maven knowledge is not that good that I could get Maven to > produce the reports. > > Linking to the "official" docs pulled from Daisy also allows more > flexibility in separate updates (I suppose the maven part is more > volatile than the docs) and in allowing a complete overhaul of either > parts without affecting the other. > > Besides, the maven part serves a different purpose than the official > docs (quick lookup vs more detailed study). So they might have a > different layout/look & feel. > > Finally, adding the proposed plugin can always be added later without > loosing the effort of the current setup. > > So +1 for Carsten's proposal. > Hmm, actually, I didn't meant my comments to be a proposal :) But i have no problem seeing it this way :) I have no idea about the effort required to get a daisy maven plugin running. But I agree totally with Reinhard, that the docs for a block belong to the block (= unit). Carsten -- Carsten Ziegeler - Open Source Group, S&N AG http://www.s-und-n.de http://www.osoco.org/weblogs/rael/
Re: Use Maven 2 for the generation of the Cocoon documentation
hepabolu wrote: Finally, adding the proposed plugin can always be added later without loosing the effort of the current setup. ok, that's right. Anyway, I can't do it myself now but if somebody is interested, I can help. Maybe some of the Daisy gurus here can comment on the idea itself? -- Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach {Software Engineering, Open Source, Web Applications, Apache Cocoon} web(log): http://www.poetz.cc ___ Telefonate ohne weitere Kosten vom PC zum PC: http://messenger.yahoo.de
Re: Use Maven 2 for the generation of the Cocoon documentation
Carsten Ziegeler said the following on 06-03-2006 17:49: I'm more than +1 for getting the reports Maven provides for us on our website. I'm not sure if we need a plugin for the daisy docs or if just linking from the maven generated site is enough. Whatever works best. Let's do this one step at a time and do Carsten's proposal first. I've been experimenting with exactly this just after the Cocoon Gettogether, but my Maven knowledge is not that good that I could get Maven to produce the reports. Linking to the "official" docs pulled from Daisy also allows more flexibility in separate updates (I suppose the maven part is more volatile than the docs) and in allowing a complete overhaul of either parts without affecting the other. Besides, the maven part serves a different purpose than the official docs (quick lookup vs more detailed study). So they might have a different layout/look & feel. Finally, adding the proposed plugin can always be added later without loosing the effort of the current setup. So +1 for Carsten's proposal. Bye, Helma
Re: Use Maven 2 for the generation of the Cocoon documentation
Carsten Ziegeler wrote: Reinhard Poetz schrieb: As written in my mail "Status of block development" (http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=114165989221631&w=2) I propose a change in the Cocoon documentation creation: We have put a lot of work into the Mavenization of the Cocoon build system. As you might know, Maven provides a site generation goal "site:site". This makes is very simple to integrate a lot of reports (javadocs, jdepend, cobertura, svn activities, ...) and uses information available in pom.xml to produce docs. IMO the only missing part is the integration of our docs that are managed by Daisy. My idea is: - write a Maven plugin that can access Daisy - it is configured by the doc-id of a navigation documentent which is the root of the block documentation - the plugin uses the Daisy client API to access this navigation doc and generates docs out of it by crawling all references docs and resources. The result of this process is added to the generated site. First, does this proposal make sense from a technical point of view? Is anybody interested in working on this? I can help with the Maven part of starting a Maven plugin project a bit. [I've cc'ed the Daisy mailing list as there might be people who are interested in such a plugin too and may consider helping out on writing it.] I'm more than +1 for getting the reports Maven provides for us on our website. I'm not sure if we need a plugin for the daisy docs or if just linking from the maven generated site is enough. Whatever works best. I consider one block as a unit and the docs are part of this unit. I want to see all pieces of information that belong to this unit, at *one* place and I don't want to distribute it. Additionally, if we use Maven as starting point for the doc generation we can use Continuum to generate our site. And because of the nature of Maven 2 we can geneate the site for one project or use a reactor build to create it all projects. -- Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach {Software Engineering, Open Source, Web Applications, Apache Cocoon} web(log): http://www.poetz.cc ___ Telefonate ohne weitere Kosten vom PC zum PC: http://messenger.yahoo.de
Re: Use Maven 2 for the generation of the Cocoon documentation
Reinhard Poetz schrieb: > As written in my mail "Status of block development" > (http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=114165989221631&w=2) I > propose > a change in the Cocoon documentation creation: > > We have put a lot of work into the Mavenization of the Cocoon build system. > As > you might know, Maven provides a site generation goal "site:site". This makes > is > very simple to integrate a lot of reports (javadocs, jdepend, cobertura, svn > activities, ...) and uses information available in pom.xml to produce docs. > > IMO the only missing part is the integration of our docs that are managed by > Daisy. My idea is: > > - write a Maven plugin that can access Daisy > - it is configured by the doc-id of a navigation documentent which is the > root of the block documentation > - the plugin uses the Daisy client API to access this navigation doc > and generates docs out of it by crawling all references docs and > resources. > The result of this process is added to the generated site. > > First, does this proposal make sense from a technical point of view? > Is anybody interested in working on this? I can help with the Maven part of > starting a Maven plugin project a bit. > > [I've cc'ed the Daisy mailing list as there might be people who are > interested > in such a plugin too and may consider helping out on writing it.] > I'm more than +1 for getting the reports Maven provides for us on our website. I'm not sure if we need a plugin for the daisy docs or if just linking from the maven generated site is enough. Whatever works best. Carsten -- Carsten Ziegeler - Open Source Group, S&N AG http://www.s-und-n.de http://www.osoco.org/weblogs/rael/
Use Maven 2 for the generation of the Cocoon documentation
As written in my mail "Status of block development" (http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=114165989221631&w=2) I propose a change in the Cocoon documentation creation: We have put a lot of work into the Mavenization of the Cocoon build system. As you might know, Maven provides a site generation goal "site:site". This makes is very simple to integrate a lot of reports (javadocs, jdepend, cobertura, svn activities, ...) and uses information available in pom.xml to produce docs. IMO the only missing part is the integration of our docs that are managed by Daisy. My idea is: - write a Maven plugin that can access Daisy - it is configured by the doc-id of a navigation documentent which is the root of the block documentation - the plugin uses the Daisy client API to access this navigation doc and generates docs out of it by crawling all references docs and resources. The result of this process is added to the generated site. First, does this proposal make sense from a technical point of view? Is anybody interested in working on this? I can help with the Maven part of starting a Maven plugin project a bit. [I've cc'ed the Daisy mailing list as there might be people who are interested in such a plugin too and may consider helping out on writing it.] WDYT? -- Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach {Software Engineering, Open Source, Web Applications, Apache Cocoon} web(log): http://www.poetz.cc ___ Telefonate ohne weitere Kosten vom PC zum PC: http://messenger.yahoo.de
[jira] Zugewiesen: (COCOON-1680) New design/ layout proposal for Cocoon documentation
[ http://issues.apache.org/jira/browse/COCOON-1680?page=all ] Jörg Heinicke reassigned COCOON-1680: - Assign To: Cocoon Developers Team > New design/ layout proposal for Cocoon documentation > > > Key: COCOON-1680 > URL: http://issues.apache.org/jira/browse/COCOON-1680 > Project: Cocoon > Type: Improvement > Components: - Documentation > Reporter: Milan Andrejevic > Assignee: Cocoon Developers Team > Priority: Minor > Attachments: asf20051107.zip, asf20051108.zip, screenshot.gif, screenshot.gif > > I made new design/ layout proposal for Cocoon documentation. Just one html > and screen css. I understand you need to "modernize" site (see Upayavira > comment for COCOON-1679). This is my try, I hope you like it. > There are two layouts user can choose. Layout info is stored in cookie > "_asfstyle" for 30 days. > Added access keys on top menu. > Navigation on right contains only sub-section selected form top menu > Minimal resolution set to 800px. > Starting design is done in Macromedia Fireworks (_src/cocoon.png) were you > can find all picture slices. > I have checked this design in: > Windows: > Firefox 1.0.7 > Internet Explorer 6.0 > Opera 8.5 > Linux: > Firefox 1.0.7 > Konqueror 3.3.2 > Mozilla 1.7.5 > Netscape 7.2 > Lynx -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (COCOON-1680) New design/ layout proposal for Cocoon documentation
[ http://issues.apache.org/jira/browse/COCOON-1680?page=comments#action_12357206 ] Milan Andrejevic commented on COCOON-1680: -- Where can I find ASF logo, new version of the feather (IIRC ASF) in vector format, or large raster format? This would help a lot. > New design/ layout proposal for Cocoon documentation > > > Key: COCOON-1680 > URL: http://issues.apache.org/jira/browse/COCOON-1680 > Project: Cocoon > Type: Improvement > Components: - Documentation > Reporter: Milan Andrejevic > Priority: Minor > Attachments: asf20051107.zip, asf20051108.zip, screenshot.gif, screenshot.gif > > I made new design/ layout proposal for Cocoon documentation. Just one html > and screen css. I understand you need to "modernize" site (see Upayavira > comment for COCOON-1679). This is my try, I hope you like it. > There are two layouts user can choose. Layout info is stored in cookie > "_asfstyle" for 30 days. > Added access keys on top menu. > Navigation on right contains only sub-section selected form top menu > Minimal resolution set to 800px. > Starting design is done in Macromedia Fireworks (_src/cocoon.png) were you > can find all picture slices. > I have checked this design in: > Windows: > Firefox 1.0.7 > Internet Explorer 6.0 > Opera 8.5 > Linux: > Firefox 1.0.7 > Konqueror 3.3.2 > Mozilla 1.7.5 > Netscape 7.2 > Lynx -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (COCOON-1680) New design/ layout proposal for Cocoon documentation
[ http://issues.apache.org/jira/browse/COCOON-1680?page=comments#action_12357191 ] Vadim Gritsenko commented on COCOON-1680: - IIRC ASF has newer version of the feather - the one which was used on AC2004 hackaton tshirts - I think it should be better then current one. Probably PRC should have it... > New design/ layout proposal for Cocoon documentation > > > Key: COCOON-1680 > URL: http://issues.apache.org/jira/browse/COCOON-1680 > Project: Cocoon > Type: Improvement > Components: - Documentation > Reporter: Milan Andrejevic > Priority: Minor > Attachments: asf20051107.zip, asf20051108.zip, screenshot.gif, screenshot.gif > > I made new design/ layout proposal for Cocoon documentation. Just one html > and screen css. I understand you need to "modernize" site (see Upayavira > comment for COCOON-1679). This is my try, I hope you like it. > There are two layouts user can choose. Layout info is stored in cookie > "_asfstyle" for 30 days. > Added access keys on top menu. > Navigation on right contains only sub-section selected form top menu > Minimal resolution set to 800px. > Starting design is done in Macromedia Fireworks (_src/cocoon.png) were you > can find all picture slices. > I have checked this design in: > Windows: > Firefox 1.0.7 > Internet Explorer 6.0 > Opera 8.5 > Linux: > Firefox 1.0.7 > Konqueror 3.3.2 > Mozilla 1.7.5 > Netscape 7.2 > Lynx -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (COCOON-1680) New design/ layout proposal for Cocoon documentation
[ http://issues.apache.org/jira/browse/COCOON-1680?page=comments#action_12357153 ] Upayavira commented on COCOON-1680: --- Keep the feather, in some form, but _much_ smaller. > New design/ layout proposal for Cocoon documentation > > > Key: COCOON-1680 > URL: http://issues.apache.org/jira/browse/COCOON-1680 > Project: Cocoon > Type: Improvement > Components: - Documentation > Reporter: Milan Andrejevic > Priority: Minor > Attachments: asf20051107.zip, asf20051108.zip, screenshot.gif, screenshot.gif > > I made new design/ layout proposal for Cocoon documentation. Just one html > and screen css. I understand you need to "modernize" site (see Upayavira > comment for COCOON-1679). This is my try, I hope you like it. > There are two layouts user can choose. Layout info is stored in cookie > "_asfstyle" for 30 days. > Added access keys on top menu. > Navigation on right contains only sub-section selected form top menu > Minimal resolution set to 800px. > Starting design is done in Macromedia Fireworks (_src/cocoon.png) were you > can find all picture slices. > I have checked this design in: > Windows: > Firefox 1.0.7 > Internet Explorer 6.0 > Opera 8.5 > Linux: > Firefox 1.0.7 > Konqueror 3.3.2 > Mozilla 1.7.5 > Netscape 7.2 > Lynx -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (COCOON-1680) New design/ layout proposal for Cocoon documentation
[ http://issues.apache.org/jira/browse/COCOON-1680?page=comments#action_12357148 ] Helma van der Linden commented on COCOON-1680: -- Right, I like the second version better, because it's less cluttered, but Upayavira is right: it still has strong resemblance to the old site. Do get wild and surprise us. I'd suggest to stick with blue (in whatever shade) to link back to old site. Also, keep the Cocoon logo (the white letters with the dots). I'm not sure if you can remove the apache logo with the feather (and just keep the feather), i.e. if there are rules on that. It would surely free up space. Keep up the good work. > New design/ layout proposal for Cocoon documentation > > > Key: COCOON-1680 > URL: http://issues.apache.org/jira/browse/COCOON-1680 > Project: Cocoon > Type: Improvement > Components: - Documentation > Reporter: Milan Andrejevic > Priority: Minor > Attachments: asf20051107.zip, asf20051108.zip, screenshot.gif, screenshot.gif > > I made new design/ layout proposal for Cocoon documentation. Just one html > and screen css. I understand you need to "modernize" site (see Upayavira > comment for COCOON-1679). This is my try, I hope you like it. > There are two layouts user can choose. Layout info is stored in cookie > "_asfstyle" for 30 days. > Added access keys on top menu. > Navigation on right contains only sub-section selected form top menu > Minimal resolution set to 800px. > Starting design is done in Macromedia Fireworks (_src/cocoon.png) were you > can find all picture slices. > I have checked this design in: > Windows: > Firefox 1.0.7 > Internet Explorer 6.0 > Opera 8.5 > Linux: > Firefox 1.0.7 > Konqueror 3.3.2 > Mozilla 1.7.5 > Netscape 7.2 > Lynx -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (COCOON-1680) New design/ layout proposal for Cocoon documentation
[ http://issues.apache.org/jira/browse/COCOON-1680?page=comments#action_12357027 ] Upayavira commented on COCOON-1680: --- Personally, I'd say "be more bold". What you're designing still feels like the old site. I'd like to see our site looking fresh, new, modern, but still connected to the 'Cocoon' brand, with the logo, maybe with colours, etc. So, be wild. Then we'll let this community restrain you. But if you start restrained, I'm scared we'll end up with something boring :-( > New design/ layout proposal for Cocoon documentation > > > Key: COCOON-1680 > URL: http://issues.apache.org/jira/browse/COCOON-1680 > Project: Cocoon > Type: Improvement > Components: - Documentation > Reporter: Milan Andrejevic > Priority: Minor > Attachments: asf20051107.zip, asf20051108.zip, screenshot.gif, screenshot.gif > > I made new design/ layout proposal for Cocoon documentation. Just one html > and screen css. I understand you need to "modernize" site (see Upayavira > comment for COCOON-1679). This is my try, I hope you like it. > There are two layouts user can choose. Layout info is stored in cookie > "_asfstyle" for 30 days. > Added access keys on top menu. > Navigation on right contains only sub-section selected form top menu > Minimal resolution set to 800px. > Starting design is done in Macromedia Fireworks (_src/cocoon.png) were you > can find all picture slices. > I have checked this design in: > Windows: > Firefox 1.0.7 > Internet Explorer 6.0 > Opera 8.5 > Linux: > Firefox 1.0.7 > Konqueror 3.3.2 > Mozilla 1.7.5 > Netscape 7.2 > Lynx -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Updated: (COCOON-1680) New design/ layout proposal for Cocoon documentation
[ http://issues.apache.org/jira/browse/COCOON-1680?page=all ] Milan Andrejevic updated COCOON-1680: - Attachment: asf20051108.zip version 2 > New design/ layout proposal for Cocoon documentation > > > Key: COCOON-1680 > URL: http://issues.apache.org/jira/browse/COCOON-1680 > Project: Cocoon > Type: Improvement > Components: - Documentation > Reporter: Milan Andrejevic > Priority: Minor > Attachments: asf20051107.zip, asf20051108.zip, screenshot.gif, screenshot.gif > > I made new design/ layout proposal for Cocoon documentation. Just one html > and screen css. I understand you need to "modernize" site (see Upayavira > comment for COCOON-1679). This is my try, I hope you like it. > There are two layouts user can choose. Layout info is stored in cookie > "_asfstyle" for 30 days. > Added access keys on top menu. > Navigation on right contains only sub-section selected form top menu > Minimal resolution set to 800px. > Starting design is done in Macromedia Fireworks (_src/cocoon.png) were you > can find all picture slices. > I have checked this design in: > Windows: > Firefox 1.0.7 > Internet Explorer 6.0 > Opera 8.5 > Linux: > Firefox 1.0.7 > Konqueror 3.3.2 > Mozilla 1.7.5 > Netscape 7.2 > Lynx -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Updated: (COCOON-1680) New design/ layout proposal for Cocoon documentation
[ http://issues.apache.org/jira/browse/COCOON-1680?page=all ] Milan Andrejevic updated COCOON-1680: - Attachment: screenshot.gif version 2 > New design/ layout proposal for Cocoon documentation > > > Key: COCOON-1680 > URL: http://issues.apache.org/jira/browse/COCOON-1680 > Project: Cocoon > Type: Improvement > Components: - Documentation > Reporter: Milan Andrejevic > Priority: Minor > Attachments: asf20051107.zip, asf20051108.zip, screenshot.gif, screenshot.gif > > I made new design/ layout proposal for Cocoon documentation. Just one html > and screen css. I understand you need to "modernize" site (see Upayavira > comment for COCOON-1679). This is my try, I hope you like it. > There are two layouts user can choose. Layout info is stored in cookie > "_asfstyle" for 30 days. > Added access keys on top menu. > Navigation on right contains only sub-section selected form top menu > Minimal resolution set to 800px. > Starting design is done in Macromedia Fireworks (_src/cocoon.png) were you > can find all picture slices. > I have checked this design in: > Windows: > Firefox 1.0.7 > Internet Explorer 6.0 > Opera 8.5 > Linux: > Firefox 1.0.7 > Konqueror 3.3.2 > Mozilla 1.7.5 > Netscape 7.2 > Lynx -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (COCOON-1680) New design/ layout proposal for Cocoon documentation
[ http://issues.apache.org/jira/browse/COCOON-1680?page=comments#action_12357024 ] Milan Andrejevic commented on COCOON-1680: -- I made some changes according to your suggestions. At the first the aim was to make new skin for http://forrest.zones.apache.org/ft/build/cocoon-docs/2.1/index.html, but I realize that this could be universal skin or all document base pages regarding Cocoon, of course if you like it. You can easily exclude sub navigation if you don't need it by removing ... > New design/ layout proposal for Cocoon documentation > > > Key: COCOON-1680 > URL: http://issues.apache.org/jira/browse/COCOON-1680 > Project: Cocoon > Type: Improvement > Components: - Documentation > Reporter: Milan Andrejevic > Priority: Minor > Attachments: asf20051107.zip, screenshot.gif > > I made new design/ layout proposal for Cocoon documentation. Just one html > and screen css. I understand you need to "modernize" site (see Upayavira > comment for COCOON-1679). This is my try, I hope you like it. > There are two layouts user can choose. Layout info is stored in cookie > "_asfstyle" for 30 days. > Added access keys on top menu. > Navigation on right contains only sub-section selected form top menu > Minimal resolution set to 800px. > Starting design is done in Macromedia Fireworks (_src/cocoon.png) were you > can find all picture slices. > I have checked this design in: > Windows: > Firefox 1.0.7 > Internet Explorer 6.0 > Opera 8.5 > Linux: > Firefox 1.0.7 > Konqueror 3.3.2 > Mozilla 1.7.5 > Netscape 7.2 > Lynx -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (COCOON-1680) New design/ layout proposal for Cocoon documentation
[ http://issues.apache.org/jira/browse/COCOON-1680?page=comments#action_12356955 ] Milan Andrejevic commented on COCOON-1680: -- Everything is changeable, but let's see some more comments. How many (maximum) menu entries are there? Please give structure for top menu(s) and sidebar menu you would like to have. >I assume they are used for keyboard shortcuts? Yes you assume right. > New design/ layout proposal for Cocoon documentation > > > Key: COCOON-1680 > URL: http://issues.apache.org/jira/browse/COCOON-1680 > Project: Cocoon > Type: Improvement > Components: - Documentation > Reporter: Milan Andrejevic > Priority: Minor > Attachments: asf20051107.zip, screenshot.gif > > I made new design/ layout proposal for Cocoon documentation. Just one html > and screen css. I understand you need to "modernize" site (see Upayavira > comment for COCOON-1679). This is my try, I hope you like it. > There are two layouts user can choose. Layout info is stored in cookie > "_asfstyle" for 30 days. > Added access keys on top menu. > Navigation on right contains only sub-section selected form top menu > Minimal resolution set to 800px. > Starting design is done in Macromedia Fireworks (_src/cocoon.png) were you > can find all picture slices. > I have checked this design in: > Windows: > Firefox 1.0.7 > Internet Explorer 6.0 > Opera 8.5 > Linux: > Firefox 1.0.7 > Konqueror 3.3.2 > Mozilla 1.7.5 > Netscape 7.2 > Lynx -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Commented: (COCOON-1680) New design/ layout proposal for Cocoon documentation
[ http://issues.apache.org/jira/browse/COCOON-1680?page=comments#action_12356951 ] Helma van der Linden commented on COCOON-1680: -- Thanks for the work done, it really looks much more modern. I like the general layout and the simplicity of the menu and main content window. I noticed a kind of top level menu in the bar at the top. I find this very cluttered, i.e. too many entries. Maybe you could go one level up for that or reduce it to: - about Cocoon (about us, status, and other info on downloads, svn access, mailing list, links etc) - user guide (narrative info about Cocoon, i.e. explanations of concepts, beginners' info etc) - reference guide (more in-depth info about various aspects of Cocoon) - apidocs and the two "Cocoon/ASF" links at the right. I do like this: simple and clear. Although you might change ASF to "Apache" since not every one is familiar with the meaning of ASF. I noticed lines above certain letters of the links. I assume they are used for keyboard shortcuts? If so, the idea is fabulous, but I would suggest to move the line below the letter or change the color of the letter. Both are more compatible with user expectations. I like it that the search bar is less prominent but as a whole I find the top block very cluttered. Is it possible to reduce the left image with the feather? > New design/ layout proposal for Cocoon documentation > > > Key: COCOON-1680 > URL: http://issues.apache.org/jira/browse/COCOON-1680 > Project: Cocoon > Type: Improvement > Components: - Documentation > Reporter: Milan Andrejevic > Priority: Minor > Attachments: asf20051107.zip, screenshot.gif > > I made new design/ layout proposal for Cocoon documentation. Just one html > and screen css. I understand you need to "modernize" site (see Upayavira > comment for COCOON-1679). This is my try, I hope you like it. > There are two layouts user can choose. Layout info is stored in cookie > "_asfstyle" for 30 days. > Added access keys on top menu. > Navigation on right contains only sub-section selected form top menu > Minimal resolution set to 800px. > Starting design is done in Macromedia Fireworks (_src/cocoon.png) were you > can find all picture slices. > I have checked this design in: > Windows: > Firefox 1.0.7 > Internet Explorer 6.0 > Opera 8.5 > Linux: > Firefox 1.0.7 > Konqueror 3.3.2 > Mozilla 1.7.5 > Netscape 7.2 > Lynx -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Updated: (COCOON-1680) New design/ layout proposal for Cocoon documentation
[ http://issues.apache.org/jira/browse/COCOON-1680?page=all ] Milan Andrejevic updated COCOON-1680: - Attachment: screenshot.gif screenshot > New design/ layout proposal for Cocoon documentation > > > Key: COCOON-1680 > URL: http://issues.apache.org/jira/browse/COCOON-1680 > Project: Cocoon > Type: Improvement > Components: - Documentation > Reporter: Milan Andrejevic > Priority: Minor > Attachments: asf20051107.zip, screenshot.gif > > I made new design/ layout proposal for Cocoon documentation. Just one html > and screen css. I understand you need to "modernize" site (see Upayavira > comment for COCOON-1679). This is my try, I hope you like it. > There are two layouts user can choose. Layout info is stored in cookie > "_asfstyle" for 30 days. > Added access keys on top menu. > Navigation on right contains only sub-section selected form top menu > Minimal resolution set to 800px. > Starting design is done in Macromedia Fireworks (_src/cocoon.png) were you > can find all picture slices. > I have checked this design in: > Windows: > Firefox 1.0.7 > Internet Explorer 6.0 > Opera 8.5 > Linux: > Firefox 1.0.7 > Konqueror 3.3.2 > Mozilla 1.7.5 > Netscape 7.2 > Lynx -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] Created: (COCOON-1680) New design/ layout proposal for Cocoon documentation
New design/ layout proposal for Cocoon documentation Key: COCOON-1680 URL: http://issues.apache.org/jira/browse/COCOON-1680 Project: Cocoon Type: Improvement Components: - Documentation Reporter: Milan Andrejevic Priority: Minor Attachments: asf20051107.zip I made new design/ layout proposal for Cocoon documentation. Just one html and screen css. I understand you need to "modernize" site (see Upayavira comment for COCOON-1679). This is my try, I hope you like it. There are two layouts user can choose. Layout info is stored in cookie "_asfstyle" for 30 days. Added access keys on top menu. Navigation on right contains only sub-section selected form top menu Minimal resolution set to 800px. Starting design is done in Macromedia Fireworks (_src/cocoon.png) were you can find all picture slices. I have checked this design in: Windows: Firefox 1.0.7 Internet Explorer 6.0 Opera 8.5 Linux: Firefox 1.0.7 Konqueror 3.3.2 Mozilla 1.7.5 Netscape 7.2 Lynx -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
Re: [Docs] Semi-automatic update process of the Cocoon documentation
David Crossley wrote: Ross Gardler wrote: hepabolu wrote: After talks to several people I feel we need a semi-automatic update process of the Cocoon documentation to cocoon.apache.org. We have always needed this, but not possible with the current setup of the project publishing mechanism at apache.org If committers want to help, then subscribe to site-dev at a.o All sounds great, in fact, most of the "automated" publishing side an be done by the ForrestBot. See http://forrest.zones.apache.org/ The forrestbot can publish via various methods including SVN. ... For Forrest's own website, the committers use a local forrestbot. Two easy commands and a publish is done: 'build; deploy'. Then we have a cronjob on the server to do 'svn update'. See forrest-trunk/etc/publishing_our_site.txt Actually, that is what I was suggestion for Cocoon in the short term. Note the subject is for a "semi-automatic" update process. That is what out local "forrest bot" process is (actually for me it is automatic because David seems to be the only one who ever runs it ;-) Use zones for the staging area (using the Forrest zone since it is already set up). Committers run locally to actually publish. That is the method that i recommend at this stage. +1 Thanks for clarifying David. Ross
Re: [Docs] Semi-automatic update process of the Cocoon documentation
Ross Gardler wrote: > hepabolu wrote: > >After talks to several people I feel we need a semi-automatic update > >process of the Cocoon documentation to cocoon.apache.org. We have always needed this, but not possible with the current setup of the project publishing mechanism at apache.org If committers want to help, then subscribe to site-dev at a.o > > > All sounds great, in fact, most of the "automated" publishing side an be > done by the ForrestBot. See http://forrest.zones.apache.org/ > > The forrestbot can publish via various methods including SVN. Yes it can. However there are issues. Apache projects store the generated documents in SVN and they are 'svn checkout' on the server to create the website. The forrestbot on our zone cannot automatically commit them to the Cocoon SVN because forrestbot has no svn account. It is not a committer. All that forrestbot can do is to generate them on to the server (i.e. a staging area) but that does not get them published onto the actual server. Hence the site-dev discussion list is addressing this and other site publishing issues. Note that our zone is still very basic, only me working there occasionally. We don't even use the zone forrestbot for the Forrest project yet (just doing some useful continuous build and error reporting so far). For Forrest's own website, the committers use a local forrestbot. Two easy commands and a publish is done: 'build; deploy'. Then we have a cronjob on the server to do 'svn update'. See forrest-trunk/etc/publishing_our_site.txt That is the method that i recommend at this stage. -David > I just have to find the time to do the test build using Forrest+Daisy > (should be in the next day or two). > > Ross
Re: [Docs] Semi-automatic update process of the Cocoon documentation
hepabolu wrote: After talks to several people I feel we need a semi-automatic update process of the Cocoon documentation to cocoon.apache.org. All sounds great, in fact, most of the "automated" publishing side an be done by the ForrestBot. See http://forrest.zones.apache.org/ The forrestbot can publish via various methods including SVN. I just have to find the time to do the test build using Forrest+Daisy (should be in the next day or two). Ross
Re: [Docs] Semi-automatic update process of the Cocoon documentation
hepabolu wrote: After talks to several people I feel we need a semi-automatic update process of the Cocoon documentation to cocoon.apache.org. Several reasons: - frequent updates show users that there is concern about their documentation wishes. We might even write documentation that answers FAQs and point the users to that, rather than rewriting the information on the mailing list. This last sentence is IMO a very good idea from the community point of view for both users and developers. - users will be educated to search first in the docs, as we will have good and up to date docs, which is a kind of revolution :-) - developers will have go to the docs in search of information, which will make them care more about it. One of the current problems is that devs don't really need docs and thus don't care much about it (as we say in France: "far from the eyes is far from the heart"). - the documentation will be frequently updated based on user feeback and questions. So this makes the documentation a part of the community conversations on the mailing-list. And this is very easy solution to help ensure it is kept up to date. - semi-automatic updates avoid the reinvention of the wheel for every committer trying to update the website and avoid the errors that created the current crippled site. - the current Daisy on the cocoon.zones contains the most recent version of the documentation and provides an easier way of adding and updating the documentation. - with the current update of Daisy, Daisy books have become available and allow the documentation to be exported as a book in both HTML and PDF. New process: - set up a small Cocoon branding website in the current xdocs section with only a few pages that contain relative static content. Compare it to the Springframework website. - These pages contain links to the actual reference documentation which are available as Daisy book in both HTML (for browsing on the website) and in PDF (for downloading and printing). - on cocoon.zones a Forrest configuration is setup with all the tweaks necessary to get the job done. - a script is created that can do the Daisy books export, do the Forrest conversion and the upload on the cocoon.apache.org site and all the necessary steps in between. - the end result of the script is that the documentation is available as a complete website on cocoon.apache.org AND for inclusion in the next Cocoon release. - a secured "button" is available for committers to start this script. Whether it is available as a password protected page, a ssh command or whatever. - a notification can be sent to the dev-list when the site update hasn't been done in X days. This last point ensure we don't let the website become obsolete, without having to setup some completely automated publication which isn't good as we must have a human oversight on what is published on the official website. WDYT? +1000 :-) It would be good to get the end result as described (but manual, rather than semi-automatic for now) ASAP for inclusion in the upcoming 2.1.8 release. Another +1000. But we should not delay the release because of this, which probably means that the docs that will be shipped with 2.1.8 will not have a nice skin. But accurate information matters more than presentation. Sylvain -- Sylvain WallezAnyware Technologies http://people.apache.org/~sylvain http://www.anyware-tech.com Apache Software Foundation Member Research & Technology Director
[Docs] Semi-automatic update process of the Cocoon documentation
After talks to several people I feel we need a semi-automatic update process of the Cocoon documentation to cocoon.apache.org. Several reasons: - frequent updates show users that there is concern about their documentation wishes. We might even write documentation that answers FAQs and point the users to that, rather than rewriting the information on the mailing list. - semi-automatic updates avoid the reinvention of the wheel for every committer trying to update the website and avoid the errors that created the current crippled site. - the current Daisy on the cocoon.zones contains the most recent version of the documentation and provides an easier way of adding and updating the documentation. - with the current update of Daisy, Daisy books have become available and allow the documentation to be exported as a book in both HTML and PDF. New process: - set up a small Cocoon branding website in the current xdocs section with only a few pages that contain relative static content. Compare it to the Springframework website. - These pages contain links to the actual reference documentation which are available as Daisy book in both HTML (for browsing on the website) and in PDF (for downloading and printing). - on cocoon.zones a Forrest configuration is setup with all the tweaks necessary to get the job done. - a script is created that can do the Daisy books export, do the Forrest conversion and the upload on the cocoon.apache.org site and all the necessary steps in between. - the end result of the script is that the documentation is available as a complete website on cocoon.apache.org AND for inclusion in the next Cocoon release. - a secured "button" is available for committers to start this script. Whether it is available as a password protected page, a ssh command or whatever. - a notification can be sent to the dev-list when the site update hasn't been done in X days. WDYT? It would be good to get the end result as described (but manual, rather than semi-automatic for now) ASAP for inclusion in the upcoming 2.1.8 release. Bye, Helma
Re: Editing Cocoon documentation
Le 26 juil. 05, à 11:15, Upayavira a écrit : ...Probably because Helios was restarted to get access to additional storage. We need to have init scripts in place if we don't have already... I thought we had for Daisy, but apparently not. And the disappearing of /var/run/apache2 is *strange*. The Cocoon demo does not have init scripts yet, but it's restarted by crontab every few hours. -Bertrand smime.p7s Description: S/MIME cryptographic signature
Re: Editing Cocoon documentation
Bertrand Delacretaz wrote: Le 26 juil. 05, à 00:53, Mark Leicester a écrit : ...I've found that http://cocoon.zones.apache.org/daisy/ seems to be down. Can anyone advise on the status?.. For some reason most services were stopped on the zone, I have restarted them. Probably because Helios was restarted to get access to additional storage. We need to have init scripts in place if we don't have already. Regards, Upayavira
Re: Editing Cocoon documentation
Le 26 juil. 05, à 00:53, Mark Leicester a écrit : ...I've found that http://cocoon.zones.apache.org/daisy/ seems to be down. Can anyone advise on the status?.. For some reason most services were stopped on the zone, I have restarted them. FYI zone admins, here's what I had to do: (as root) mkdir /var/run/apache2 (was missing, prevented httpd from starting???) apachectl -k start su - daisy ./dsy_openjms.sh start ./dsy_repo.sh start ./dsy_wiki.sh start -Bertrand smime.p7s Description: S/MIME cryptographic signature
Editing Cocoon documentation
Hi all, After an absence from things Cocoon for a few weeks, I've just popped back to a little more documenting, but I've found that http://cocoon.zones.apache.org/daisy/ seems to be down. Can anyone advise on the status? Cheers, Mark
Re: Cocoon documentation (was: RE: Community health)
Linden H van der (MI) wrote: As explained in a private mail to Sebastien, I've taken up the http://www.cocoondev.org/handbook site that Steven graciously set up for me. I intend to work on the "mid-level" tutorial that was the initial goal for the Cocoon In Action project. Doing it in Daisy is much easier for me, since it gives me quick access to an editable environment. When it amounts to something useful, I'll happily cooperate in transferring it into the "official docs". Anyone willing to contribute is welcome, but simple peeks are fine too. Bye, Helma Helma, you rock! That's the style we all love :-) -- Stefano.
RE: Cocoon documentation (was: RE: Community health)
Great! Thanks for the offer, but let's wait until there is more than one or two pages of information. Bye, Helma > -Original Message- > From: Ross Gardler [mailto:[EMAIL PROTECTED] > Sent: Thursday, 12 May, 2005 14:48 > To: dev@cocoon.apache.org > Subject: Re: Cocoon documentation (was: RE: Community health) > > > Linden H van der (MI) wrote: > > As explained in a private mail to Sebastien, I've taken up the > > http://www.cocoondev.org/handbook site that Steven > graciously set up for me. I intend to work on the "mid-level" > tutorial that was the initial goal for the Cocoon In Action project. > > Doing it in Daisy is much easier for me, since it gives me > quick access to an editable environment. When it amounts to > something useful, I'll happily cooperate in transferring it > into the "official docs". > > The Daisy plugin for Forrest is working (to a point). Images do not > currently work, but someone will get the itch sooner or later. > > This means that the pages of this handbook can be included in the > official Cocoon documentation by simply adding links in the existing > site definition. It will be included with the Cocoon skin and > navigation > and therefore the integration is seemless. > > This plugin is curently in whiteboard and is yet to be rigourously > tested, if you want to see how it works and include any > sections of this > handbook let me know, I'll do the necessary for you. > > Ross >
Re: Cocoon documentation (was: RE: Community health)
Linden H van der (MI) wrote: As explained in a private mail to Sebastien, I've taken up the http://www.cocoondev.org/handbook site that Steven graciously set up for me. I intend to work on the "mid-level" tutorial that was the initial goal for the Cocoon In Action project. Doing it in Daisy is much easier for me, since it gives me quick access to an editable environment. When it amounts to something useful, I'll happily cooperate in transferring it into the "official docs". The Daisy plugin for Forrest is working (to a point). Images do not currently work, but someone will get the itch sooner or later. This means that the pages of this handbook can be included in the official Cocoon documentation by simply adding links in the existing site definition. It will be included with the Cocoon skin and navigation and therefore the integration is seemless. This plugin is curently in whiteboard and is yet to be rigourously tested, if you want to see how it works and include any sections of this handbook let me know, I'll do the necessary for you. Ross
Re: Cocoon documentation (was: RE: Community health)
On 12 May 2005, at 14:01, Sylvain Wallez wrote: Linden H van der (MI) wrote: As explained in a private mail to Sebastien, I've taken up the http://www.cocoondev.org/handbook site that Steven graciously set up for me. I intend to work on the "mid-level" tutorial that was the initial goal for the Cocoon In Action project. Doing it in Daisy is much easier for me, since it gives me quick access to an editable environment. When it amounts to something useful, I'll happily cooperate in transferring it into the "official docs". Anyone willing to contribute is welcome, but simple peeks are fine too. How can one have write access to this to directly provide content rather than sending patches? Register on the cocoondev.org website and LMK. Ditto for cocoongt.org as of 5 minutes ago, BTW. -- Steven Noelshttp://outerthought.org/ Outerthought - Open Source Java & XMLAn Orixo Member Read my weblog athttp://blogs.cocoondev.org/stevenn/ stevenn at outerthought.orgstevenn at apache.org
RE: Cocoon documentation (was: RE: Community health)
> >As explained in a private mail to Sebastien, I've taken up the > >http://www.cocoondev.org/handbook site that Steven > graciously set up for me. I intend to work on the "mid-level" > tutorial that was the initial goal for the Cocoon In Action project. > >Doing it in Daisy is much easier for me, since it gives me > quick access to an editable environment. When it amounts to > something useful, I'll happily cooperate in transferring it > into the "official docs". > > > >Anyone willing to contribute is welcome, but simple peeks > are fine too. > > > > > > How can one have write access to this to directly provide > content rather > than sending patches? You can register (see menu under user:guest) and then ask Steven to give you editor access. Thanks. Bye, Helma
Re: Cocoon documentation (was: RE: Community health)
Linden H van der (MI) wrote: As explained in a private mail to Sebastien, I've taken up the http://www.cocoondev.org/handbook site that Steven graciously set up for me. I intend to work on the "mid-level" tutorial that was the initial goal for the Cocoon In Action project. Doing it in Daisy is much easier for me, since it gives me quick access to an editable environment. When it amounts to something useful, I'll happily cooperate in transferring it into the "official docs". Anyone willing to contribute is welcome, but simple peeks are fine too. How can one have write access to this to directly provide content rather than sending patches? Sylvain -- Sylvain WallezAnyware Technologies http://apache.org/~sylvainhttp://anyware-tech.com Apache Software Foundation Member Research & Technology Director
Cocoon documentation (was: RE: Community health)
As explained in a private mail to Sebastien, I've taken up the http://www.cocoondev.org/handbook site that Steven graciously set up for me. I intend to work on the "mid-level" tutorial that was the initial goal for the Cocoon In Action project. Doing it in Daisy is much easier for me, since it gives me quick access to an editable environment. When it amounts to something useful, I'll happily cooperate in transferring it into the "official docs". Anyone willing to contribute is welcome, but simple peeks are fine too. Bye, Helma > -Original Message- > From: Bertrand Delacretaz [mailto:[EMAIL PROTECTED] > Sent: Thursday, 12 May, 2005 08:24 > To: dev@cocoon.apache.org > Subject: Re: Community health > > > Le 11 mai 05, à 21:10, Sebastien Arbogast a écrit : > > ...So WDYT ? Stefano ? Bertrand ? Sylvain ? Upayavira ? > Helma ? Others > > I > > forgot ? ... > > My position has not changed: I think our documentation tools are > adequate today (I didn't say perfect), see [1]. > > But if people don't contribute > content/reviews/reorganization, nothing > happens. More tools with no one to use them won't bring anything, in > the end someone has to do the work and this is not happening ATM. > > -Bertrand > > > [1] http://wiki.apache.org/cocoon/22NewDocumentsGeneration >
Re: Status new Cocoon documentation
Reinhard Poetz wrote: > Upayavira wrote: > >David Crossley wrote: [snip] > >>The trouble that i have with the new documentation proposal is that > >>docs sources are moving to another part of the repository, so how > >>will 'build docs' be able to access them? I suppose that assumed default > >>relative pathnames with lots of dot-dots. > > > >A different part of the repository? Well, they'll according to the > >proposal, they'll soon be moving back into where they have always been > >in trunk (src/documentation). So I don't see what the problem is there. > > I think so too. After understanding now how it works, there shouldn't be > any problems as we can use the same behaviour in the future. Great ... it turned into a non-issue. > >Maybe you're referring to block documentation (for which there actually > >isn't any at the moment). This I guess would need to be dot-dots back to > >a checkout of the blocks repository or repositories - or more likely > >each block would have its own forrestbot setup (assuming that isn't too > >complex). Not complex. > If a block has its own docs repository (I will setup one for the Portal > block) it should also be built by forrestbot. Let me know when you are ready and i will add it to brutus. > David, do you have any further questions about "auto-docs"? Not at this stage. --David
Re: Status new Cocoon documentation
Upayavira wrote: David Crossley wrote: Upayavira wrote: David Crossley wrote: Here is one thing that i cannot grasp yet: How will the automatically generated "Sitemap Component Documentation" (i.e. the old /userdocs/) fit in with these static repositories? Currently we need to run 'build docs' to prepare them, then do 'forrest'. http://cocoon.apache.org/2.1/plan/review-sitemap-docs.html How is it done now on Brutus? Isn't there a hook within Forrest to call Cocoon's "build docs" before building the site? That way, the automatic enhancement of the docs is always done on top of whatever is in the new repository, much as it is now. Have I missed something? That is correct - the forrestbot is doing what you say. At the moment i have a wrapper shell script that first does an svn update of Cocoon's java sources and core blocks, calls 'build docs', then the forrestbot takes over. That works but is cumbersome. Evidently forrestbot itself could call Cocoon's 'docs' ant target prior to starting. I am working during spare time to get that happening, as there are various glitches. The trouble that i have with the new documentation proposal is that docs sources are moving to another part of the repository, so how will 'build docs' be able to access them? I suppose that assumed default relative pathnames with lots of dot-dots. A different part of the repository? Well, they'll according to the proposal, they'll soon be moving back into where they have always been in trunk (src/documentation). So I don't see what the problem is there. I think so too. After understanding now how it works, there shouldn't be any problems as we can use the same behaviour in the future. Maybe you're referring to block documentation (for which there actually isn't any at the moment). This I guess would need to be dot-dots back to a checkout of the blocks repository or repositories - or more likely each block would have its own forrestbot setup (assuming that isn't too complex). If a block has its own docs repository (I will setup one for the Portal block) it should also be built by forrestbot. David, do you have any further questions about "auto-docs"? -- Reinhard Pötz Independant Consultant, Trainer & (IT)-Coach {Software Engineering, Open Source, Web Applications, Apache Cocoon} web(log): http://www.poetz.cc
Re: Status new Cocoon documentation
David Crossley wrote: Upayavira wrote: David Crossley wrote: Here is one thing that i cannot grasp yet: How will the automatically generated "Sitemap Component Documentation" (i.e. the old /userdocs/) fit in with these static repositories? Currently we need to run 'build docs' to prepare them, then do 'forrest'. http://cocoon.apache.org/2.1/plan/review-sitemap-docs.html How is it done now on Brutus? Isn't there a hook within Forrest to call Cocoon's "build docs" before building the site? That way, the automatic enhancement of the docs is always done on top of whatever is in the new repository, much as it is now. Have I missed something? That is correct - the forrestbot is doing what you say. At the moment i have a wrapper shell script that first does an svn update of Cocoon's java sources and core blocks, calls 'build docs', then the forrestbot takes over. That works but is cumbersome. Evidently forrestbot itself could call Cocoon's 'docs' ant target prior to starting. I am working during spare time to get that happening, as there are various glitches. The trouble that i have with the new documentation proposal is that docs sources are moving to another part of the repository, so how will 'build docs' be able to access them? I suppose that assumed default relative pathnames with lots of dot-dots. A different part of the repository? Well, they'll according to the proposal, they'll soon be moving back into where they have always been in trunk (src/documentation). So I don't see what the problem is there. Maybe you're referring to block documentation (for which there actually isn't any at the moment). This I guess would need to be dot-dots back to a checkout of the blocks repository or repositories - or more likely each block would have its own forrestbot setup (assuming that isn't too complex). Does that make more sense? Regards, Upayavira
Re: Status new Cocoon documentation
Upayavira wrote: > David Crossley wrote: > > > >Here is one thing that i cannot grasp yet: > >How will the automatically generated "Sitemap Component Documentation" > >(i.e. the old /userdocs/) fit in with these static repositories? > >Currently we need to run 'build docs' to prepare them, then do 'forrest'. > >http://cocoon.apache.org/2.1/plan/review-sitemap-docs.html > > How is it done now on Brutus? Isn't there a hook within Forrest to call > Cocoon's "build docs" before building the site? That way, the automatic > enhancement of the docs is always done on top of whatever is in the new > repository, much as it is now. > > Have I missed something? That is correct - the forrestbot is doing what you say. At the moment i have a wrapper shell script that first does an svn update of Cocoon's java sources and core blocks, calls 'build docs', then the forrestbot takes over. That works but is cumbersome. Evidently forrestbot itself could call Cocoon's 'docs' ant target prior to starting. I am working during spare time to get that happening, as there are various glitches. The trouble that i have with the new documentation proposal is that docs sources are moving to another part of the repository, so how will 'build docs' be able to access them? I suppose that assumed default relative pathnames with lots of dot-dots. --David
Re: Status new Cocoon documentation
Reinhard Poetz wrote: > David Crossley wrote: > > >Here is one thing that i cannot grasp yet: > >How will the automatically generated "Sitemap Component Documentation" > >(i.e. the old /userdocs/) fit in with these static repositories? > >Currently we need to run 'build docs' to prepare them, then do 'forrest'. > >http://cocoon.apache.org/2.1/plan/review-sitemap-docs.html > > For me it's very important that whatever the solution is, it must be usable > with forrestbot because otherwise we would lose the automatic deployment. > > IIUC you build the sitemap-component-docs (SCD) on your local machine and > commit them into the SVN, don't you? I am not sure what you are asking. The 'build docs' generates some extra xml source for forrest to consume. It copies the xml sources to a temp directory, generates the installing/jars.xml, re-writes the /userdocs/*.xml by reading the original manually maintained content and merging it with stuff gathered from the relevant *.java source. Nothing is committed to svn there. Then forrest is called to generate the html/pdf which is then manually committed to cocoon-site svn. > You ask how this can be done with the static repositories. I see following > alternatives: > > 1) do it similarly as it is done now. Have an Ant target that generates the > SCD file and it has to be committed into SVN whenever we think that it has > to be updated. > > pro: simple > con: danger of out-dated docs Sorry, i don't understand Option 1. What gets committed to SVN? > 2) automatic process that generates the SCD and commits them into our SVN > > pro: docs are up-to-date > con: IIUC this isn't allowed because of Apache policies (not automatic > commits) IIUC policies can be changed if all bases are covered. > 3) tweak Forrest so that it can call Ant targets (checkout sources, > generate SCD) > > pro: solution within Forrest > con: a lot of work, upgrade to the unstable Forrest 0.7 I have actually considered that that is probably the best. Personally i don't have the wherewithall to do that at the moment. > 4) build and deploy the SCD without Forrest and put the SCD docs into > http://cocoon.apache.org/2.2/sitemap-components/ and > > If the docs are build at your local machine this could be achieved by an > Ant target that runs forrest, a sitemap-components-generation-target and > the javadocs-target. > > pro: to Forrest changes, SCD are up-to-date > con: The disadvantage of this solution is that those generated docs don't > use the general skin and are not within the menu structure. That's no > problem for the javadocs but for the sitemap components docs. That sounds like just as much work as the other solutions >- o - > > For SCD I propose 1) so that SCD use the style and the navigation and for > Javadocs option 4) > > WDY(O)T? I would like to hear. --David
Re: Status new Cocoon documentation
David Crossley wrote: Reinhard Poetz wrote: Last week Upayavira and I spent some time to overhaul the structure of the two document repositories: - http://brutus.apache.org/docs/build/cocoon-doco-2-2/ - http://brutus.apache.org/docs/build/cocoon-doco-global/ We think that it covers all Cocoon relevant topics and is a good starting point to evaluate and move over all existing documents. As this will be a lot of work we need all the help we can get. Check out http://wiki.apache.org/cocoon/CocoonDocumentationSystemHowTo what you have to do actually. Apart from helping to move over docs into our new repositories, my next steps are to: 1. finish my work on forrest repositories (comment and metadata part) 2. make the two repositories (currently they are in http://svn.a.o/r/a(cocoon/whiteboard/doc-repos) the official doc repositories of Cocoon 2.2 and move them over to the appropriate places (I will call for a vote on this very soon) Here is one thing that i cannot grasp yet: How will the automatically generated "Sitemap Component Documentation" (i.e. the old /userdocs/) fit in with these static repositories? Currently we need to run 'build docs' to prepare them, then do 'forrest'. http://cocoon.apache.org/2.1/plan/review-sitemap-docs.html How is it done now on Brutus? Isn't there a hook within Forrest to call Cocoon's "build docs" before building the site? That way, the automatic enhancement of the docs is always done on top of whatever is in the new repository, much as it is now. Have I missed something? Regards, Upayavira
Re: Status new Cocoon documentation
David Crossley wrote: Here is one thing that i cannot grasp yet: How will the automatically generated "Sitemap Component Documentation" (i.e. the old /userdocs/) fit in with these static repositories? Currently we need to run 'build docs' to prepare them, then do 'forrest'. http://cocoon.apache.org/2.1/plan/review-sitemap-docs.html For me it's very important that whatever the solution is, it must be usable with forrestbot because otherwise we would lose the automatic deployment. IIUC you build the sitemap-component-docs (SCD) on your local machine and commit them into the SVN, don't you? You ask how this can be done with the static repositories. I see following alternatives: 1) do it similarly as it is done now. Have an Ant target that generates the SCD file and it has to be committed into SVN whenever we think that it has to be updated. pro: simple con: danger of out-dated docs 2) automatic process that generates the SCD and commits them into our SVN pro: docs are up-to-date con: IIUC this isn't allowed because of Apache policies (not automatic commits) 3) tweak Forrest so that it can call Ant targets (checkout sources, generate SCD) pro: solution within Forrest con: a lot of work, upgrade to the unstable Forrest 0.7 4) build and deploy the SCD without Forrest and put the SCD docs into http://cocoon.apache.org/2.2/sitemap-components/ and If the docs are build at your local machine this could be achieved by an Ant target that runs forrest, a sitemap-components-generation-target and the javadocs-target. pro: to Forrest changes, SCD are up-to-date con: The disadvantage of this solution is that those generated docs don't use the general skin and are not within the menu structure. That's no problem for the javadocs but for the sitemap components docs. - o - For SCD I propose 1) so that SCD use the style and the navigation and for Javadocs option 4) WDY(O)T? -- Reinhard Pötz Independant Consultant, Trainer & (IT)-Coach {Software Engineering, Open Source, Web Applications, Apache Cocoon} web(log): http://www.poetz.cc
Re: Status new Cocoon documentation
Reinhard Poetz wrote: > > Last week Upayavira and I spent some time to overhaul the structure of the > two > document repositories: > > - http://brutus.apache.org/docs/build/cocoon-doco-2-2/ > - http://brutus.apache.org/docs/build/cocoon-doco-global/ > > We think that it covers all Cocoon relevant topics and is a good starting > point > to evaluate and move over all existing documents. As this will be a lot of > work > we need all the help we can get. > > Check out http://wiki.apache.org/cocoon/CocoonDocumentationSystemHowTo what > you > have to do actually. > > > Apart from helping to move over docs into our new repositories, my next > steps > are to: > > 1. finish my work on forrest repositories (comment and metadata part) > 2. make the two repositories (currently they are in >http://svn.a.o/r/a(cocoon/whiteboard/doc-repos) the official doc >repositories >of Cocoon 2.2 and move them over to the appropriate places (I will call >for a >vote on this very soon) Here is one thing that i cannot grasp yet: How will the automatically generated "Sitemap Component Documentation" (i.e. the old /userdocs/) fit in with these static repositories? Currently we need to run 'build docs' to prepare them, then do 'forrest'. http://cocoon.apache.org/2.1/plan/review-sitemap-docs.html --David > 3. call for help on [EMAIL PROTECTED] (writing docs) > 4. work the online editor for docs (Jeremy, thanks again for your work on > how >to access SVN using webdav!!!) > > > -- > Reinhard P?tz Independant Consultant, Trainer & (IT)-Coach > > {Software Engineering, Open Source, Web Applications, Apache Cocoon} > >web(log): http://www.poetz.cc >
Status new Cocoon documentation
Last week Upayavira and I spent some time to overhaul the structure of the two document repositories: - http://brutus.apache.org/docs/build/cocoon-doco-2-2/ - http://brutus.apache.org/docs/build/cocoon-doco-global/ We think that it covers all Cocoon relevant topics and is a good starting point to evaluate and move over all existing documents. As this will be a lot of work we need all the help we can get. Check out http://wiki.apache.org/cocoon/CocoonDocumentationSystemHowTo what you have to do actually. Apart from helping to move over docs into our new repositories, my next steps are to: 1. finish my work on forrest repositories (comment and metadata part) 2. make the two repositories (currently they are in http://svn.a.o/r/a(cocoon/whiteboard/doc-repos) the official doc repositories of Cocoon 2.2 and move them over to the appropriate places (I will call for a vote on this very soon) 3. call for help on [EMAIL PROTECTED] (writing docs) 4. work the online editor for docs (Jeremy, thanks again for your work on how to access SVN using webdav!!!) -- Reinhard Pötz Independant Consultant, Trainer & (IT)-Coach {Software Engineering, Open Source, Web Applications, Apache Cocoon} web(log): http://www.poetz.cc
Re: [proposal] Cocoon documentation system
Andreas Kuckartz wrote: > > Look at http://wiki.apache.org/cocoon/CocoonDocumentationSystem and find all > my > > requirements. I'm sure that all six options are good enough but as *I* have > > to > > do it, I'll take the road that's the fastest for *me*. > > There was a misunderstanding on my side. I had thought that that was to be a > project of the Apache Cocoon community and that other Cocoon-developers would > also participate. In any case I wish you success with your project. Wait. Any developer can be involved and all ideas are good. Reinhard is running, the rest of us can catch up and help. Lenya is not ruled out. In fact, all those options that Reinhard listed could be used in parallel. The thing is, that we are trying to get started with something right now, start small and build up. --David
Re: [proposal] Cocoon documentation system
> > Actually, and I'm not joking, I think we should have a hero plate on our > web page and put the name and have a nomination!... some ego stimulation > goes a lng way... h Wow, employee^H^H^H^H^H^H^H^Hcommitter of the month! Now that would feel like working at McDonald's :-) -- Gianugo Rabellino Pro-netics s.r.l. - http://www.pro-netics.com Orixo, the XML business alliance: http://www.orixo.com (blogging at http://www.rabellino.it/blog/)
Re: [proposal] Cocoon documentation system
Sylvain Wallez wrote: Stefano Mazzocchi wrote: Bertrand Delacretaz wrote: Le 18 janv. 05, à 09:59, Reinhard Poetz a écrit : ...as *I* have to do it, I'll take the road that's the fastest for *me*... +1, whoever does the work gets to decide (and later the community decides to use the stuff or not, but in this case I'm not worried ;-) +1, darwin and do-ocracy do the job a lot better. If I were the one to do it I would start with the requirements and get there with the simplest thing that can possibly work... and work from there. So, go Reinhard! :-) [sylvain, you'd better keep up buddy, or I might change my hero plate ;-)] Grmmbl... You're challenging me ;-) Anyway, I hope your hero plate is large enough to hold the names of everybody that deserves it. Keep up the good job, Reinhard! Nah, the hero plate holds only *one* person at a time :-) Actually, and I'm not joking, I think we should have a hero plate on our web page and put the name and have a nomination!... some ego stimulation goes a lng way... h -- Stefano.
Re: [proposal] Cocoon documentation system
Stefano Mazzocchi wrote: Bertrand Delacretaz wrote: Le 18 janv. 05, à 09:59, Reinhard Poetz a écrit : ...as *I* have to do it, I'll take the road that's the fastest for *me*... +1, whoever does the work gets to decide (and later the community decides to use the stuff or not, but in this case I'm not worried ;-) +1, darwin and do-ocracy do the job a lot better. If I were the one to do it I would start with the requirements and get there with the simplest thing that can possibly work... and work from there. So, go Reinhard! :-) [sylvain, you'd better keep up buddy, or I might change my hero plate ;-)] Grmmbl... You're challenging me ;-) Anyway, I hope your hero plate is large enough to hold the names of everybody that deserves it. Keep up the good job, Reinhard! Sylvain, in a conference room at the ObjectWebCon -- Sylvain Wallez Anyware Technologies http://www.apache.org/~sylvain http://www.anyware-tech.com { XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
Re: [proposal] Cocoon documentation system
Reinhard Poetz wrote: > David Crossley wrote: > >Reinhard Poetz wrote: > > Yep. I hope that I can convince at least one of them to help me. Actually I > need some Java code ;-) So here I ask officially: Who volunteers to write > the Java code that communicates with the SVN repository (read and commit)? Dunno. At forrest-dev, Dave Brondsema used "jsvn" for the forrestbot. > >>- enable the publishing process (forrestbot or cron) > > Unfortunatly I don't have any experience with setting up this publishing > process. David, do you know who I can ping to get help here? See below. > >Both. > > > >At forrest-dev we are also starting to set up a demo > >of the new forrestbot and its webapp interface. > >So yes, we will be able to help on some aspects. > > > >The "Proposal for ASF-wide documentation staging and publishing" > >intends to enable various document management systems to > >feed into staging areas. I will add a para to the wiki page. > > Can you give me a pointer to this document? http://forrest.apache.org/proposal-asf-publish.html not restricted to forrest tools. And i am setting up a demo on brutus as we speak. More about that soon. --David
Re: [proposal] Cocoon documentation system
David Crossley wrote: Reinhard Poetz wrote: Thank you. But as you say, it depends if it is allowed that either a webapp or a mail server is allowed to do a commit. If yes, we have many options. With the current situation, that is a no. Evidently there are solutions on the way. Spurts of discussion happen on [EMAIL PROTECTED] (like right now). In the meantime, we can get the demo on brutus happening. If no, having a locally running application that does the actual commit could be a workaround and I think rather comfortable for committers. Not sure what you mean. How can other people make changes? Doc authors do their changes via a web application. Only the approval process is done via a local running application, that also is responsible for the commit. But as being said, let's see what will happen, when we have a working solution that "only" needs to find a secure home. -- Reinhard
Re: [proposal] Cocoon documentation system
Reinhard Poetz wrote: > > Thank you. But as you say, it depends if it is allowed that either a webapp > or a mail server is allowed to do a commit. If yes, we have many options. With the current situation, that is a no. Evidently there are solutions on the way. Spurts of discussion happen on [EMAIL PROTECTED] (like right now). In the meantime, we can get the demo on brutus happening. > If no, having a locally running application that does the actual commit > could be a workaround and I think rather comfortable for committers. Not sure what you mean. How can other people make changes? --David
Re: [proposal] Cocoon documentation system
Nicola Ken Barozzi wrote: Reinhard Poetz wrote: ... ... and if there is no other way, I have ideas to perfectly work around the ASF infrastructure without having to forbear from online editing. IMHO enough bike-shedding on this thread. You know what is available, you know what you want to do. Whatever you do or choose, I'll be very happy :-) Amen :-) -- Stefano.
Re: [OT] svn libraries (Re: [proposal] Cocoon documentation system)
Torsten Curdt wrote: We had so many problems with subclipse under linux that we finally went back to the commandline! ...maybe it's worth giving it another try. But a few months ago subclipse with JNI was just a PITA. Of course using JNI will result in more pain than a pure java library and if there was such a thing, I would not hesisate to use that one instead. "Pure Java Subversion (SVN) Client Library" - http://www.tmate.org/svn/ JIRA uses this for its Subversion support. It has worked pretty well for us so far. Cool ...you can hook it into subclipse! http://www.tmate.org/svn/subclipse.html And also IDEA is using it... Thanks for the pointer, mate! AWESOME!!! -- Stefano... going to play with it!!!
Re: [proposal] Cocoon documentation system
Steven Noels wrote: On 18 Jan 2005, at 10:59, Reinhard Poetz wrote: I'm not in the position to change the ASF policy and I don't have the energy to lead all the necessary discussions. Sure. Ditto here. :-) Besides, the ASF policy is sound, if only optimized a wee bit towards source code governance and the risk of trojans being embedded in our products, rather than documentation sites being hacked. Very true... and cocoon (then forrest, then lenya) were seeded by me with the intention of changing that. 6 years later, still no chance. I think it's time I step down and let somebody else do it because, honeslty, I think I suck at doing that :-) I prefer Daisy users to make a positive choice instead (look at all the features I got!) rather than a negative one (only 85% of my requirements are addressed so I'm doomed). Look at how Jira (and in the future perhaps Confluence) quickly won lots of ASF users - even though Jira is a pig to keep running (Daisy isn't). I understand that part of the requirements is to comply with the existing ASF infrastructure. I've had my opportunity to run a non-ASF-infra-resource for two years, and I'm happy that I don't have to check server logs of the Wiki anymore. I do hate the current documentation system and MoinMoin wiki with a passion though, as its split personality is obviously not helping people to produce better documentation. So we definitely need one system, which supports both Wiki-style grassroots authoring, and a proper software documentation CMS. And yes, ASF-compliancy means we should be careful about security if we want to run alongside the code repositories. The only thing I am worried about is that your system will add a third option, and that you'll feel the pain in supporting it as I've felt with the JSPWiki at times. If I choose Daisy or whatever I could feel the same pain. In all my projects I've done so far, Cocoon runs pretty stable *and* in this community there are one or two Cocoon specialists available that could help out ;-) And of course the plan is to have the webapp running on ASF infrastructure. First on brutus.apache.org and I'm sure we get a secure server that is allowed to access our SVN repo, if tests on brutus run well. I'm not so optimistic about a) the chance that automated SVN commit access using role accounts will be granted, I hear you, but there is a difference now: granular SVN authentication. You can "sandbox" your documents and you are guaranteed that no trojians will get in your code. This was not possible with CVS... well, it was, but it was a pain to convince them. The problem was to try to convince them before having something running. Since the Gump PMC controls brutus, and brutus is already not considered safe, we can do whatever we want there, including having our own svn repository for docs. But more than anything, we need something working! and b) whether the technicalities of a secure webapp which is tied to the ASF web of trust (keys, certificates) will get solved properly. yeah, don't hold your breath. That's why I'm steering clear of the ASF infrastructure issue. We can't possible require the ASF to host a specialized documentation system, since Cocoon will want to use Cocoon, some Geronimites are eager of Confluence, old-school folks prefer Anakia, etc etc. I know there's efforts underway to provide people with machine VMs that they can play with at leisure, but the infra folks remain severely understaffed (look at how SVN itself is doing lately), and I'm not sure whether there will ever be willingness to grant access from such an untrusted VM to the trusted SVN repo server. the fact is, *we* don't need that. brutus is not super-secure, but it's, IMO, secure enough for content. I mean, if you have an "edit this page" link on the page itself, people will not see defacing as a problem with the apache web server security... we are long past that which was the entire point. One thing to add: Of course I don't commit myself to provide a 24/7 support. Maybe my attempt will fail, don't know. Maybe somebody else will jump in then, I don't know. Maybe it's the start of a new area in Cocoon documentation, who knows. I think Cocoon needs better documentation, not a new area. ;-) What I fail to understand is your apparent eagerness to get going, yet you want to focus first on rebuilding things which are already readily accessible. IMHO, the documentation issue is only editorial, not technical. I agree and disagree at the same time. There would be no wikipedia if it wasn't easy to use and we would have better docs and less wiki pages, if it was easier to edit the docs directly. The only logistical issue we should address is merging the xdocs with the Wiki. The day our documentation infrastructure is successful is the day the cocoon wiki gets zero activity. -- Stefano.
Re: [proposal] Cocoon documentation system
Bertrand Delacretaz wrote: Le 18 janv. 05, à 09:59, Reinhard Poetz a écrit : ...as *I* have to do it, I'll take the road that's the fastest for *me*... +1, whoever does the work gets to decide (and later the community decides to use the stuff or not, but in this case I'm not worried ;-) +1, darwin and do-ocracy do the job a lot better. If I were the one to do it I would start with the requirements and get there with the simplest thing that can possibly work... and work from there. So, go Reinhard! :-) [sylvain, you'd better keep up buddy, or I might change my hero plate ;-)] -- Stefano.
Re: [proposal] Cocoon documentation system
Torsten Curdt wrote: every new/modified doc has to be approved by a committer. My plan is, that this approval is part of the online webapp. >RT> Why not simple moderation via email? Committers could subscribe to a special closed mailing list. The webapp send emails with diffs and a link with a token. If anyone clicks on the link the webapp will commit the change. Well, or you could even count the clicks and require e.g. 3 committers to acknowledge the change ...things like that. Due to the amount of committers we would have still quite a good response time until changes appear live. ...which is important IMHO. Though I doubt the infrastructure folks would like to give a webapp commit privileges. Actually it would also be even nice to pass on the credentials of the clicking/committing committer. So using a ssh to execute a remote command would be another option... The point to success: it must be comfortable - for users and committers. My 2 cents Thank you. But as you say, it depends if it is allowed that either a webapp or a mail server is allowed to do a commit. If yes, we have many options. If no, having a locally running application that does the actual commit could be a workaround and I think rather comfortable for committers. -- Reinhard
Re: [proposal] Cocoon documentation system
Stefano Mazzocchi wrote: As for french docs, I *strongly* think that we should do this thru content-negotiation rather than URL design. A person accessing the page with a french browser will get the page in french, that's all they have to know Can you rely that each person in France will have "french" browser? Can you rely that each french speaking Canadian will have "french" browser? I'm really curious as I've never seen "accept-language" header used at all (probably because nobody I knew had "russian" browser). (and the page will have a series of flags that will trigger an overload in locale, but that's going to be a parameter of the URL, not part of it). One thing I noticed is that it's harder to be cache friendly when page content variates depending on session attribute ("locale" in this case), and /en/ segment makes it trivial to support reverse proxies. How do you propose to solve this without uri segment - by preserving this request parameter, adding it to each link? Or do you see a better way? Vadim
Re: [proposal] Cocoon documentation system
every new/modified doc has to be approved by a committer. My plan is, that this approval is part of the online webapp. >RT> Why not simple moderation via email? Committers could subscribe to a special closed mailing list. The webapp send emails with diffs and a link with a token. If anyone clicks on the link the webapp will commit the change. Well, or you could even count the clicks and require e.g. 3 committers to acknowledge the change ...things like that. Due to the amount of committers we would have still quite a good response time until changes appear live. ...which is important IMHO. Though I doubt the infrastructure folks would like to give a webapp commit privileges. Actually it would also be even nice to pass on the credentials of the clicking/committing committer. So using a ssh to execute a remote command would be another option... The point to success: it must be comfortable - for users and committers. My 2 cents -- Torsten