cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <terrac...@mac.com>
Subject Re: Docs: next steps scratchpad and new mailing list
Date Fri, 03 May 2002 11:41:06 GMT

On May 3, 2002, David Crossley wrote:

> A) Establish a new area under scratchpad for the Draft
> documentation, probably at src/scratchpad/documentation/

As per my earlier post on file naming conventions, I think we need a 
similar setup:
   src/scratchpad/documentation/xdocs/faqs/XXXXXX.xml
   src/scratchpad/documentation/xdocs/howtos/XXXXXX.xml (or XXXXX 
directories for multi-page docs)
   src/scratchpad/documentation/xdocs/tutorials/XXXXXX.xml (or XXXXX 
directories for multi-page docs)
   src/scratchpad/documentation/xdocs/examples/XXXXXX.xml (or XXXXX 
directories for multi-page docs)
   src/scratchpad/documentation/xdocs/guides/XXXXXX.xml (or XXXXX 
directories for multi-page docs)

The examples section is intended to include community contributions of 
static and dynamic code snippets. I think Cocoon's current dynamic 
examples need static overview pages with links as appropriate to the 
dynamic pages which illustrate functionality. The page layout of the 
example overview should be follow the documentation skin used by other 
docs. I think any build should be able to distinguish static 
documentation from dynamic (examples). In other words, dynamic example 
pages shouldn't be integrated into the static build.


> I will start to investigate that, though i will certainly need help
> with Cocoon's Ant build.xml files ... wow, they are complex.

We need to make it easy for QA people, some of whom are probably going 
to be somewhat conservative (and newbie) users. I'm not sure builds are 
right for everyone, especially those who don't (yet) keep up with the 
head branch. Do we have *any* meaningful statistics as to how many 
people download binaries vs. source files? Do we know if users actually 
build their versions or simply download the latest binaries?

Some preliminary thoughts:
- a downloadable minimal WAR just for scratchpad (and existing) 
documentation work, based on release features, not head. This could be a 
variation of the MyApp project Konstantin is developing.
- downloadable files containing scratchpad docs which users drop into a 
documentation directory of sorts
- a separate cvs branch, just for docs

I'm not suggesting we don't need builds for this. I just think we need a 
few more options to meet the future needs of all contributors.

Diana


---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message