Re: Documenting Packages for Future Developers

On 14/01/2009, at 10:18 AM, Israel Saeta Pérez 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. :-)

awesome work.

>
> 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.

I'd say the opposite is true. By keeping it "modular" you increase the  
risk of breaking other parts by making giving conflicting advice in  
two different documents. Sure we shouldn't entagle the documentation  
is one part relies on the other but all I'm saying is that we somehow  
review documentation as a whole so it presents the least confusing  
view of plone at a code level as possible.
NB Not talking about user level manual. Thats fantastic as it is, and  
is one big manual.

>
> - 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.

I see no difference with indexing based on task whatever way we  
structure it. I'd just like to see us not avoid the hard problem of  
making plone code easy to understand to newbies. thats all.



> 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.

Totally disagree. Zope/Plone desperately needs to be explained from a  
code level how it all fits. Its a daunting task but should we avoid it  
just because its hard?  Our learning curve is 6 months where it could  
be 2. Published books aren't the answer either as they go out of date  
too quickly and besides, aren't we open source? It also hurts our  
brand if we say you get the code for free but have to pay for  
documentation. Most importantly of all, developers are the laziest  
bunch of people on the planet, and possibly the cheapest. The most  
approachable platform is going to be popular and from an integrators  
point of view, we really need a lot more developers right now.
Cutting down the documentation task into little chunks doesn't give us  
the place to explain how it all fits together. Without a place to  
explain, people who want to explain, like me and others, have no place  
to do so. Instead we get 50 explanations in blogs and tutorials spread  
all over the internet, all subtly different and the result is confusion.
Perhaps now is not the time for the doc team to take this on board but  
at some stage I'd like to contribute to something that makes Plone  
easy to understand to a developer, beginning to end. Don't get me  
wrong. you guys are doing an awesome job. I'm just trying to be helpful.


> -- 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


------------------------------------------------------------------------------
Create and Deploy Rich Internet Apps outside the browser with Adobe(R)AIR(TM)
software. With Adobe AIR, Ajax developers can use existing skills and code to
build responsive, highly engaging applications that combine the power of local
resources and data with the reach of the web. Download the Adobe AIR SDK and
Ajax docs to start building applications today-http://p.sf.net/sfu/adobe-com