Re: Documenting Packages for Future Developers

Hello Dylan,

We're already collaborating with the Framework Team to try to document
changes introduced by the accepted PLIPs in each version. Hopefully
this will help us to keep official documentation a bit more up to
date. :-)

Regarding the big-manual thing, I think we should keep documentation
as modular as possible because:
 - It makes easier to edit a page without worrying too much about
breaking other parts of the documentation.
 - it allows readers to find and read only the pages they need to
perform a certain task, without having to read the whole big-manual
like if it were a book.

But I'm open to contra-arguments.

We reference some manuals from other ones when necessary, e.g. the
GenericSetup manual from the Archetypes manual when explaining the GS
bits, and avoid duplicating already existing information (hyperlinks
are our friends), to keep the documentation as cohesive as possible.

I formerly thought we needed to explain how all parts of Plone fit
together, but now I realize the complexity of Plone and Zope makes
this too hard (and probably unnecessary) and a manual for each main
topic is fairly enough.

-- israel

------------------------------------------------------------------------------
This SF.net email is sponsored by:
SourcForge Community
SourceForge wants to tell your story.
http://p.sf.net/sfu/sf-spreadtheword