cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andy Lewis" <>
Subject Re: Documentation Format...
Date Fri, 15 Nov 2002 18:56:22 GMT

It would be, without a doubt, a huge undertaking. But, the current documentation is not organized
in a "scalable" and "maintainble" way for developers and writers, there is no single clear
or format to introduce complete documentation for componenet "X" once written (I could easily
wrong on this one, but I haven't seen it), and as it stnads it is still very hard to find
your way
around as a user.

> Makes at lot of sense.  As Cocoon uses many components, it makes sense for  the reference
> to follow the pattern, even more once Blocks are here, as  each Block will need its own
> documentation.


> I think a single FileGenerator page, for example, could include information  for both
users and
> developers, assuming a strict page structure (DTD) is  adhered to. The "DTD" of unix
man pages
> is certainly a good starting point  for this.

a clean doc type is certainy the corect starting point here

> This might mean restructuring much of the docs, trying to get obvious URLs  like
>  docs/components/generators/FileGenerator.html
>  docs/components/serializers/PDFSerializer.html
> (and later)
>  docs/blocks/pdf/fop/FopPdfBlock.html

I'm not sure if it would need to have that kind of heirarchical organization or not. I would
to eventually have a good interface for accessing them (a block no doubt) through Cocoon.
> etc...
> Problem is, do we have the resources for what could be a major restructuring  of the
> including DTD design? The fairly slow activity on the -docs list  makes me a little wary
> starting big documentation projects, as lack of  resources might cause them to fail.

there are never resources for a big documentation project unless you are the government (which,
although I currently work for thme, I am not)
I would hope we could get soem decent feedback on DTD design by taking, say, one components,
using it as an example. As far as resources for the restructuring, no, they propably aren't
to make a compelte sweep through in a short time period. I would be including to instead start
slow migration, in parallel to existing  docs. Encourage new components and new versions of
compoenents to move to the man page model when they are updated. This is not a "sexy" part
of the
project, so a big-bang approach won't be likley to succeed here. This will have to be slow,
methodical, and incremental or it simply won't happen. tell me if I am overly skeptical here.
> Would you or your team be able to contribute to this "docs refactoring"  project?

I am not sure if I am in a position to speak for anyone other than myself. I will actively
contribute to the DTD, and once that is compelted, I should be able to conrbiute some time
documenting components. I am trying to get to where I can donate a lot more to this project.
also may be able to drum up some other volunteers...
> -Bertrand

"The heights of genius are only measurable by the depths of stupidity."

View raw message