Re: Documenting Packages for Future Developers

> I realise a big manual is more work and harder to comprehend than
> keeping them small but I think its worth the extra effort.
> I'm sure it will all work in the wash and I'll have a go organising
> the documentation list you've compiled into some kind of chapter
> structure and see how it looks.

Once again, this is Israel's call on how the section should be
organized. While I'm sure he appreciates any and all input, it's
ultimately up to him on how manuals and docs are organized within the
section.


> We need a place to put the goals of plone code and where all the
> details fit in.

The goals of the code is something that falls under the Framework
team. It's not for the doc team to speculate on. We document
functionality as it is. It's up to the developers to discuss goals of
code/products and that discussion does not take place in these docs.


We need to glue all the different bits of developer/
> integrator documentation to make it make sense.
> The reason a bigger manual is better is to make that explanation of
> plone is as cohesive as possible. so any change is reviewed against
> the whole manual.

Cohesive is good but just because a manual is big, does not make it
cohesive or good. If you want a big manual, buy a book. Online
documentation is meant to be modular and deliver what you need just in
time. There is no reason a series of manuals can not be in a suggested
order. But there is nothing here that you've mentioned that makes a
case for why a large manual is better than a series of smaller ones.
Ultimately, this is personal preference.
I'm encouraging editors to go with the smaller manuals option because
they are easier to maintain, easier to get volunteers to tackle
smaller subjects, and less menacing looking to newbies when they are
first learning a subject.


> don't you think its how all the pieces of plone fit togeather that we
> are missing?

I don't disagree on this in principal, but I don't think having a huge
manual is going to give us a full picture either. We do have some
pretty good conceptual stuff in the end user manuals that give a good
idea of how things fit together.

------------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It is the best place to buy or sell services for
just about anything Open Source.
http://p.sf.net/sfu/Xq1LFB