cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@indexgeo.com.au>
Subject Re: Sorting out the docs
Date Fri, 21 Mar 2003 06:51:29 GMT
Andrew Savory wrote:
> Here's what I'm going to do to try and resolve some of the documentation
> issues we're having (the issues I see are maintenance of multiple
> documentation branches, indicating deprecation in documentation,
> extracting meaningful documentation from the code, and increasing semantic
> quality of content):
>
> - Take a look at Forrest and try and get the Cocoon Forrest transition
> complete. This will probably include hassling the Forrest folk to add
> deprecation to their DTDs.

Please join the effort. The transition will definitely
take more than one person. I presume that you have seen
the Wiki ForrestProposal.

No need to "hassle" .. forrest-dev is keen to facilitate any
real-world need. Just clearly define what is needed here and
we will then post to forrest-dev list.

Here is the reference that Diana was looking for in another thread:
http://cvs.apache.org/viewcvs.cgi/xml-forrest/etc/DTD_DEFICIENCIES.txt?rev=HEAD&content-type=text/vnd.viewcvs-markup

> - Try merging a few sample documents from the 2.0 and 2.1 tree into a c2
> common version to see how it might work. Particular sticking points might
> be the INSTALL doc which will vary greatly and version-specific docs - how
> do we act if no version is given?

We tried not to have many differences between the xdocs
in 2.1 and 2.0 ... Diana, and various other people, worked
hard to keep it in sync. It just needs a uniform way to
note which branch certain paragraphs refer to. There are
only a few documents where there are specific differences
in each branch (they could certainly be unified).

> - Try out a few examples of literate programming on the logicsheets
> (putting documentation into the XSL and processing in a similar way to
> javadocs)

Would you please explain a bit more about what you mean by
"literate programming".

> - Look at how the literate XSL documentation will affect the current
> documentation. I expect the current documentation will become more
> "howto/example/demo" related, and possibly even obsolete in
> favour of the wiki.

I expect that the Cocoon xdocs evolve into a truly
excellent and authoritative resource. I doubt that the
Wiki will replace that. Wiki is great as a breeding ground
and for supplemental documentation. However, i fear that
it could needlessly duplicate stuff that is in xdocs.

> I'll keep you posted as I progress. Here come some sleepless nights! :-)

Glad that you are keen.

--David




Mime
View raw message