Re: Documenting Packages for Future Developers

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.



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


Come on, you don't *have to* pay for documentation. There's a lot of free
documentation for Plone in the web, and there are books about it too, like
it happens with any other mature opensource project. See Drupal, Django,
Squid, SQLAlchemy...

I absolutely agree the Plone world is really lack of developers, and
certainly people say the learning curve is hard.


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

Python is how it all fits together. I personally can't see a way to explain
how all Plone modules fit together, because I don't understand Plone as a
whole. I know how to create and subclass content-types, I know how to create
page templates and make them available, register CSS & Javascript resources,
etc. etc. but not *how Plone works*. Even Martin's book doesn't explain
Plone as a whole, it just explains each major part of it and join them
throught a common project, Optilux Cinemas.

Don't worry, the chunks are not going to be tiny, like glossary entries, but
full-fledged manuals about each topic. And as I've already stated, I'm sure
they will converge *naturally* if we have enough time and manpower.

We're trying to keep only *one* explanation for each task in the (incoming)
official Plone.org documentation, so avoiding duplication as possible.

Finally, if you really want to be helpful, start helping! There are lots of
tasks filed in Trac which need some care. Take one and work on it. I will
personally grant you appropiate permissions where needed.

 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

_______________________________________________
Plone-docs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/plone-docs