Re: [Plone-docs] Documentation Thoughts

[Andy M. <an...@ag...>]

> 1. I did not use CMF before using plone, but I had used Zope. So it was
> not apparent to me that content as added from within Plone as opposed to
> from the ZMI. Much of the current documentation on CMF (basicly the CMF
> list) is developer oriented. Answers that assume years of experience with
> CMF don't work for newcomers. Saying "Google this" or "subclass that"
> might be sufficient for developers, but is pretty dense otherwise.

Yes my basic assumption is that Plone documentation should be stand alone.
Plone brings many new users into the Zope fold and I think we need to make
that assumption. Thats why on chapter 5
(http://plone.org/documentation/book/5) I suddenly realised, golly I have to
explain the ZMI, because chances are a user wont know what it is.

> 2. Do we need to separate Zope | CMF | Plone functionality and
> documentation? I know we don't want to doc all 3 things (a life's work!)
> but new users need to know what ZMI means, and need to know what "It's in
> the properties tab" means. Perhaps some agreement on what components of
> these other pieces does Plone need to address to make sure the Plone user
> has a positive experience, or does not spend too long floundering around
> trying to figure out something that resides outside of Plone.

You're right we cant document all 3 things, but there are areas where we
will have to. We can't just say go read the Zope Book. We can give a bit of
an overview, enough to get some one working and then point them off in the
direction of the Zope Book for the rest.

I tried to sum this in appendix d: http://plone.org/documentation/book/d but
if in anyone wants to start figuring out concrete rules, Im all ears ;)
Looking at that statement now I realise I need to relax it a bit.

> 3. Case-based documentation. There have been some discussions lately on
> Plone-users(?) about customizing news items so that content is added,
> published to a news folder, etc. It would be great to document a real-life
> case like one of these. It gets into permissions, workflows, content
> management -- the real meat of taking Plone and making it work for you.
> Or is this a Tutorials Appendix or something like that?

Yep I think you are right, see earlier email with Amr about the ZopeZen skin
docs, I think this is the way to go. The Plone book works you through all
the key points examples, and then we build up some tutorials / how tos in an
appendix dealing with a special use case.
--
  Andy McKay
  www.agmweb.ca


----- Original Message -----
From: "Steve Rauch" <srauch@u.washington.edu>
To: <plo...@li...>
Sent: Friday, October 18, 2002 9:57 AM
Subject: [Plone-docs] Documentation Thoughts


> I am really pleased to see this effort taking wing! I will try to add what
> I can to assist the effort.
>
> These are just a couple thoughts I had that I wanted to share -- mostly to
> help me get a grip on my own need for Plone documentation.
>
> 1. I did not use CMF before using plone, but I had used Zope. So it was
> not apparent to me that content as added from within Plone as opposed to
> from the ZMI. Much of the current documentation on CMF (basicly the CMF
> list) is developer oriented. Answers that assume years of experience with
> CMF don't work for newcomers. Saying "Google this" or "subclass that"
> might be sufficient for developers, but is pretty dense otherwise.
>
> 2. Do we need to separate Zope | CMF | Plone functionality and
> documentation? I know we don't want to doc all 3 things (a life's work!)
> but new users need to know what ZMI means, and need to know what "It's in
> the properties tab" means. Perhaps some agreement on what components of
> these other pieces does Plone need to address to make sure the Plone user
> has a positive experience, or does not spend too long floundering around
> trying to figure out something that resides outside of Plone.
>
> 3. Case-based documentation. There have been some discussions lately on
> Plone-users(?) about customizing news items so that content is added,
> published to a news folder, etc. It would be great to document a real-life
> case like one of these. It gets into permissions, workflows, content
> management -- the real meat of taking Plone and making it work for you.
> Or is this a Tutorials Appendix or something like that?
>
>
> Thx --
>
> Steve Rauch
>
>
>
>
>
> -------------------------------------------------------
> This sf.net email is sponsored by:ThinkGeek
> Welcome to geek heaven.
> http://thinkgeek.com/sf
> _______________________________________________
> Plone-docs mailing list
> Plo...@li...
> https://lists.sourceforge.net/lists/listinfo/plone-docs
>