On Wednesday, March 12, 2003, at 09:17 AM, Andrew Savory wrote:
Do you have a particular approach in mind? If so, then this discussion should probably continue on cocoon-docs.
Ok: here's what I'd suggest. It may not be the most efficient or scientific way, but it will certainly be methodical.
- Create cocoon-doc CVS module - Populate with content from cocoon-2.1 - Remove cocoon-2.1 docs and point at cocoon-doc - Individually review 2.0 docs, merging with cocoon-doc content where applicable - Remove cocoon-2.0 docs and point at cocoon-doc
Problems with this approach:
- Getting it done quickly enough that changes to docs in 2.0 don't fall through the cracks. I don't know if we could/should somehow "freeze" 2.0 docs during the process. This will depend greatly on likely time to completion.
I don't see why a freeze would be a problem. Docs simply aren't updated that often. :( We could also have a testing/prototype phase using ant scripts to pull content from both repositories.
Also, there seem to be a number of ways to indicate the version in the docs. A quick random sample:
xdocs/faq/faq-sitemap.xml:cachability (since 2.1)
xdocs/howto/howto-flow-debugger.xml:<note>Since: 2.1 2002-12-07</note>
xdocs/userdocs/matchers/template-matcher.xml:<td>SINCE</td><td>Cocoon X.Y</td
xdocs/faq/faq-xslt.xml:Yes. For Cocoon version 2.0.3
xdocs/howto/howto-paginator-transformer.xml:Make sure you have the version 2.0.3 or greater of Cocoon.
etc etc. So we should probably decide on a standard way to denote all of these (I think SINCE is the preferred method?).
Why can't we use page-based metadata for versioning? It's not as efficient when your content isn't very granular (e.g. page-based as above), but it will work well for faqs/snippets/how-tos ATM and more complex docs could be refactored down the road (e.g. topic map approach). Embedding "since" in one form or the other sounds kind of messy (maintenance and editing-wise) to me, unless it's an attribute of some kind. Think what it will be like supporting versions 2.0x, 2.1x, 2.2x, ... I'm not an expert here, so I'll defer to those with more CMS expertise.
I'm also wondering if we should take this opportunity to add some good
quality metadata to the docs, for example using Dublin Core. This will add
some much needed semantisation, make the docs more widely (and accurately)
visible, and all the other benefits usually associated with resource
description. Here's a possible example:
<?xml version="1.0"?> <!DOCTYPE rdf:RDF SYSTEM "http://purl.org/dc/schemas/dcmes-xml-20000714.dtd";>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"; xmlns:dc="http://purl.org/dc/elements/1.1/";> <rdf:Description about="http://url.of.page";> <dc:title/> <dc:creator/> <dc:subject/> <dc:description/> <dc:contributor/> <dc:publisher>Apache Software Foundation</dc:publisher> <dc:date/> <dc:type/> <dc:format/> <dc:language/> <dc:relation/> <dc:coverage/> <dc:identifier/> </rdf:Description> </rdf:RDF>
Before you all go "eek!" and run away, most of these fields can be automagically generated either by CVS (contributor, creator, date) or by stylesheets (type and format).
I looked at this about a year ago and thought it not expressive enough for our needs. It's isn't obvious to me how/if the above might handle software release versioning. Suggestions?
This allows some seriously cool stuff: cocoon-docs as RDF/RSS (anyone for
a "cocoon-docs latest additions" news feed?), cocoon-docs as an OAI data
provider, to name but two.
Sure, let's hope...
What do you all think?
Great start, Andrew. Thanks.
Diana
