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 place or format to introduce complete documentation for componenet "X" once written (I could easily be 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. <snip/>
> Makes at lot of sense. As Cocoon uses many components, it makes sense for > the reference docs > to follow the pattern, even more once Blocks are here, as each Block will > need its own modular > documentation. > exactly > 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 hope 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 docs, > including DTD design? The fairly slow activity on the -docs list makes me a > little wary of > 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, and using it as an example. As far as resources for the restructuring, no, they propably aren't there to make a compelte sweep through in a short time period. I would be including to instead start a 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 to documenting components. I am trying to get to where I can donate a lot more to this project. I also may be able to drum up some other volunteers... > > -Bertrand -- "The heights of genius are only measurable by the depths of stupidity."
