Re: Documenting Packages for Future Developers

I think having a handful of manuals makes it easier to solicit authoring
help on a given topic. And, many of these are already written, so why add
more work by trying to combine them?

If it makes sense to string them together in a given order, that can
probably be accomplished, which sounds like the argument that was being
posed...

- Veda


On 1/13/09 3:18 PM, "Israel Saeta Pérez" <[email protected]> wrote:

> 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
> _______________________________________________
> Plone-docs mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/plone-docs


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