Re: Expanding on Plone User Manual with additional use cases

Upon further review, I see that Khairil's question brings to light a basic
problem Darci and I faced on the user manual. We were working independently
on various sections, while communicating back and forth frequently, but I
recall that we acknowledged the challenge of structuring the parts, while
managing to incorporate previous work effectively.

The section at the end of the "folder-view" page Khairil cited, is currently
titled "Setting an Individual Content Item as the View for a Folder." Two
scenarios are presented for using the Display View: for creating a custom
folder hierarchy with author-managed links or graphics with links, and for
using a folder as a file repository, with only one file published and the
stale versions set as private.  The third bullet point here addresses the
flexible nature and central role of Plone folders, but only touches a few
angles.  These blurbs jump the gun on introducing more advanced concepts --
hence, Khairil's reference to this spot.

Meanwhile, Darci's
"publication-workflow-and-collaboration/collaboration-through-sharing" page
is good, covering a scenario wherein several users share a folder, but it
lives several major sections downstream within the user manual beyond the
finish of the basic "Managing Content" section. Darci describes the use of
the "Can Add," "Can Edit," "Can View," and "Can Review" permissions in this
page about the Sharing tab on folders. This treatment comes after sections
on publication states and workflow.

I am thinking about the following significant changes to the flow and
structure of the user manual to improve the order of presentation after the
basic "Managing Content" section.

First, edit the bottom of the "Folder View" page, under the section "Setting
an Individual Content Item as the View for a Folder" to describe only the
basics, limiting the treatment to setting a single page as the default view
for a folder, without saying too much about the implications. The three
bullet points that describe usage scenarios would be removed. The reader
would not be prompted to think too deeply about site structure,
collaboration, and other things to come later. Scrub the other parts of the
"Managing Content" section in this regard.

Second, move the entire section titled "Publication, Workflow, and
Collaboration" to just after the existing, basic "Managing Content" section.
Break the "Publication, Workflow, and Collaboration" content into two
sections, one called "Site Structure and Content Publication" and the other
called "Collaboration and Workflow." The sections would comprise:

Site Structure and Content Publication

Incorporate the essence of the blurbs removed from the bottom of the "Folder
View" page into the introduction of this section -- Folders are the
bread-and-butter of Plone, and can be used in a variety of ways, using the
functions described in the previous section (the "Managing Content"
section). Specifically, the functions treated would include the Display View
of folders, basic publication states, publishing and retracting content,
using date/time to control content visibility, more on versioning,
controlling appearance of content within the navigation menu, etc. This
section would _not_ address elements of collaboration and workflow.

Collaboration and Workflow

Start with an introduction to describe the breadth of things possible for
collaboration and list scenarios. Incorporate Darci's existing page on the
Sharing tab functions with new content along the lines Khailil described,
wherein several other scenarios are described for basic collaboration.
Include description of enabling comments. Give workflow the same treatment.
First introduce the breadth of things possible and list scenarios. Expand
the existing single page on workflow, then pick a few scenarios to expand
for illustration.

The remaining sections of the user manual would be:

Using Collections
Portlet Management
Next Steps

The section on "Portlet Managment" comes appropriately at the end, after
first, a focus on folders and content, then collections, which are "smart
folders," as you recall. Coverage would seem to "ramp up" to portlets.

The user manual, as I think of it, is more than a dry treatment of clicks
and screenshots (it has to cover the basics, yes), but serves as an
introduction for new users, as one port-of-entry, of sorts. We should
optimize its coverage, leveraging the attention we have from the reader, to
tweak the order of presentation and points made. Incorporating synoptic
views of scenarios is important. They should not be full-blown "how-tos,"
but basic scenario descriptions, hopefully prompting the reader to say "Ah,
I see...," or "I can see the potential here..." I think the reorganizing and
slight expansion of content will pay off.

These changes would not be made to the 2.5 manual.

Jeff

Jeff Pittman
http://www.geojeff.org


On Sat, Mar 28, 2009 at 10:30 PM, djay <nabble-Q+/Sk2sTzaxWk0Htik3J/[email protected]> wrote:

>
>
> Here's drupals site recipes.
> http://drupal.org/handbook/site-recipes
> Note all drupal's documentation is wiki now and I think site-recipes and
> howtos really do (as Joanna sugests) have to be in hte community section as
> these are the kind of thing that will get updated regularly. And may have
> different ways of achieving the same result which people should feel free to
> include as an alternative on the same page.
>
>
> I was talking to a guy in the drupal community the other day and
> they've recently restructered their docs. One thing they use a lot of
> is "Site recipes". Howtos on how people solved particular problems on
> particular sites. Given that such uses cases as described below could
> be many and varied, perhaps its a better idea for them to go into the
> upcomming wiki documentation area rather than manuals? Perhaps the
> concept of Site Recipe could fit well with us too, including buildout
> examples, permissions structure, and which 3rd party products were used.
>
>
> On 28/03/2009, at 11:28 PM, Jeff Pittman wrote:
>
> > Hi Khairil,
> >
> > I think it would be great to incorporate those into the existing
> > user manual in the "managing-content" area. If they won't fit within
> > the existing pages, we could insert a page called "more examples" at
> > that point.
> >
> > Maybe you would want to contribute a "more examples" page to get the
> > new examples going -- I would be glad to work with you to help
> > insert it.
> >
> > Jeff
> >
> > Jeff Pittman
> > http://www.geojeff.org
> >
> >
> > On Sat, Mar 28, 2009 at 5:19 AM, Khairil Yusof <kaeru@inigo-
> > tech.com> wrote:
> > Getting them technically done is explained well in the existing
> > manual,
> > and examples provided here as points at the end of this page:
> >
> >
> http://plone.org/documentation/manual/plone-3-user-manual/managing-content/folder-view
> >
> > I'm however getting common requests from different users, who seem to
> > have trouble converting it to their use cases.
> >
> > The request for my users (government/NGO project websites) usually
> > revolve around "collaborative spaces" use cases.
> >
> > * Joe want to put up drafts of documents for feedback (comments).
> >
> > * Jane wants to create a wiki (usually they just mean enable Sharing)
> >  - container folder, wiki markup, enable comments (talk), history
> >
> > * Joe and Jane, want to collaborate on a workshop event, where
> >  they would have a shared folder to collaborate on pages such
> >  as agenda, schedule, news, event item, photos and maybe video
> >  gallery
> >
> > I'm wondering, is there a place (or need) on Plone.org for step by
> > step
> > illustrated guide of examples in same style as the user manual to put
> > these up?
> >
> > Would Examples in the existing manual to expand on the points at the
> > url
> > mentioned in the manual be appropriate? They're kinda like programming
> > recipes, except for users.
> >
> > I'm already working on these for my users, and would love to
> > contribute
> > them to plone doc efforts if possible.
> >
> > Regards
> >
> >
> >
> ------------------------------------------------------------------------------
> > _______________________________________________
> > Plone-docs mailing list
> > [email protected]
> > https://lists.sourceforge.net/lists/listinfo/plone-docs
> >
> >
> ------------------------------------------------------------------------------
> > _______________________________________________
> > Plone-docs mailing list
> > [email protected]
> > https://lists.sourceforge.net/lists/listinfo/plone-docs
>
>
>
> ------------------------------------------------------------------------------
> _______________________________________________
> Plone-docs mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/plone-docs
>
>
>
> --
> View this message in context:
> http://n2.nabble.com/Expanding-on-Plone-User-Manual-with-additional-use-cases-tp2548585p2551336.html
> Sent from the Documentation Team mailing list archive at Nabble.com.
>
>
>
> ------------------------------------------------------------------------------
> _______________________________________________
> Plone-docs mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/plone-docs
>

------------------------------------------------------------------------------

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