Re: Expanding on user manual

Jeff - 

All good ideas. I think what you're noticing is the fact that the end user manual needs a bit of weeding and organizing. If you want to take on the changes you mention below, please go right ahead. I also agree that the manual should have examples of specific use cases. I know there are some in there, but there's probably room for more. 

Sam


Message: 2
Date: Sun, 29 Mar 2009 08:56:53 -0500
From: Jeff Pittman <[email protected]>
Subject: Re: [Plone-docs] Expanding on Plone User Manual with
	additional use	cases
To: djay <nabble-Q+/Sk2sTzaxWk0Htik3J/[email protected]>
Cc: [email protected]
Message-ID:
	<1253ecbd0903290656o51d298f6u70b223ef17b2b455-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
Content-Type: text/plain; charset="iso-8859-1"

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

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

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