cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tony Collen <>
Subject Re: Do we need to scrap the existing docs and start over?
Date Thu, 03 Apr 2003 07:29:25 GMT
On Thu, 3 Apr 2003, Bertrand Delacretaz wrote:

> Reading Tony Collen's weblog at
> reinforces my thinking
> that the current organization does not allow the kind of disruptive
> work that is needed to make the docs happen.

Ohhh. Readers!   Always a nice surprise :)


> 1) We're afraid of breaking the existing docs or offending their
> authors by making big changes to the navigation/layout/content/whatever

Hmm.  I'd say most of it is the first one (breaking the docs).  But that
might just be because I'm still not 100% comfortable with the source
directory layout.

We should all know layout is not a concern to us (let the Forrest
stylesheets worry about it), and Navigation isn't really a concern either,
except for maybe linking to other documents.  So perhaps it's not knowing
how documents are rendered/named/whatever in relation to their position in
the CVS tree.

> 2) There is no sandbox where to safely experiment in small steps. The
> wiki is good for experimental content but not to work on the
> navigation/structure/presentation of the Cocoon web site.
> But small steps and concrete results (=documents, navigation, layout,
> search features) are needed to converge the excellent ideas that have
> been exchanged here in the last few months.

Here's our main concerns in order of importance:

1. Content
2. Organization

We already have lots of 1, which is actually a problem now because it is
loosely organized.  When I wrote out that big outline of what a "Cocoon
Manual" would be, Diana mentioned something to the effect that it was a
very "top-down" approach, which I took to mean that I just sort of made it
up without actually looking to see what we have.  Which is exactly what I
did.  Now, however, I see that what we need to do is take #1 and apply #2
to it.

That is, based on the content we have, what organization can come of it?

And once we have Organization, Navigation will organically come from it.

And we still don't have to worry about stuff like layout and presentation

> I think it is critical that we allow people to work in small increments
> on this move: most probably several of us, like me, can commit small
> amounts of time to this here and there, but not the two-weeks full-time
> that would be needed for the big reworking that is (IMHO) needed.

Oh man, If I could spare 2 weeks paid vacation, I'd already have something
big done.  Oh well.. that's what I get for being a full time student and
working part-time as well.

> Here's what I suggest:
> -create a new-docs subdirectory in the  (cocoon-2.1 or cocoon-docs) CVS
> -configure an alternate Forrest-based docs build using this as input
> -use this a a scratchpad to create a new web site with better
> navigation and more consistent content, starting from scratch
> -gradually bring over the best existing CVS and wiki docs
> -switch the web site to new-docs once they are good enough

How about a new-docs block or something?  Then when we think they're
'ready', switch them over to replace what's there.

If not a block, let's at least get a new-documentation directory setup.

New Docs on the Block.... oh man.. yeah, time for bed.



Tony Collen
ICQ: 12410567
Cocoon: Internet Glue (A Cocoon Weblog)

View raw message