Re: Documenting Packages for Future Developers

On 03/02/2009, at 7:42 PM, Israel Saeta Pérez wrote:

> On Tue, Feb 3, 2009 at 1:29 AM, Dylan Jay wrote:
>
> On 14/01/2009, at 10:18 AM, Israel Saeta Pérez wrote:
> 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.
>
> Reviewing all documentation as a whole is perfect as a wish, but I'm  
> convinced that's impossible with the current manpower and scattered  
> documentation. We first need to create comprhensive modular manuals,  
> linking between them when needed, and I'm sure some of them will  
> eventually and naturally converge and be merged.

Great. If the goal is to make plone easy to understand for developers  
then I for one am willing to help, especially if we build to a  
structure like Mikko has outlined. Thanks for the bug list, that helps  
a lot.

It takes a lot to make the ideas in my head make sense to other on  
paper (and often I'm not successful... you may have noticed). I might  
be better off helping with coding which is why I've previously  
volunteered with sphinx. Seems like there's still a need to get code  
based docs into plone.org so they can be mixed with manual content. If  
so I' can raise a task and work on that. Otherwise I'll pick something  
off the list.

PS. I didn't say you had to pay for plone documentation or that other  
projects don't have books. Just that we need quality developer docs  
that are free, which I'm sure we're not in disagreement about.


>
>  http://dev.plone.org/plone/report/25
>
> -- israel
>


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