Re: Plone-docs Digest, Vol 31, Issue 9

I realize I'm weighing in on this a little late so forgive me if what I
say here has already been said. I agree with Steve - we only need one
Plone 3.x manual. The existing one is in decent shape but could use a
little help. For example the section called Adding a Page is really,
really long and could be broken into smaller chunks as it covers a lot
more than the title suggests. 

Jeff - I'd be happy to go over the manual with you at some point if
you'd like. 

Sam Knox |  Support Manager
ONE/Northwest

-----Original Message-----
From: plone-docs-request-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org
[mailto:plone-docs-request-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org] 
Sent: Saturday, December 20, 2008 11:02 AM
To: [email protected]
Subject: Plone-docs Digest, Vol 31, Issue 9

Send Plone-docs mailing list submissions to
	[email protected]

To subscribe or unsubscribe via the World Wide Web, visit
	https://lists.sourceforge.net/lists/listinfo/plone-docs
or, via email, send a message with subject or body 'help' to
	plone-docs-request-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org

You can reach the person managing the list at
	plone-docs-owner-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org

When replying, please edit your Subject line so it is more specific
than "Re: Contents of Plone-docs digest..."


Today's Topics:

   1. Re: Plone 3.2 User Manual Update (Jeff Pittman)
   2. Re: Plone 3.2 User Manual Update (JoAnna Springsteen)
   3. Re: Plone 3.2 User Manual Update (JoAnna Springsteen)
   4. Re: Plone 3.2 User Manual Update (Jeff Pittman)
   5. Re: Plone 3.2 User Manual Update (Steve McMahon)
   6. Re: Plone 3.2 User Manual Update (Steve McMahon)


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

Message: 1
Date: Sat, 20 Dec 2008 12:18:17 -0600
From: "Jeff Pittman" <[email protected]>
Subject: Re: [Plone-docs] Plone 3.2 User Manual Update
To: "JoAnna Springsteen" <[email protected]>
Cc: "[email protected]"
	<[email protected]>
Message-ID:
	<1253ecbd0812201018o58500270x55c5e0c4ad834fb1-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
Content-Type: text/plain; charset="iso-8859-1"

Love the python.

The sections would be stored in svn?, so contributing wouldn't be a
problem,
eh?

Jeff

Jeff Pittman
http://www.geojeff.org


On Sat, Dec 20, 2008 at 12:15 PM, JoAnna Springsteen
<[email protected]>wrote:

> On Sat, Dec 20, 2008 at 11:21 AM, Jeff Pittman <[email protected]>
> wrote:
> > The manual could be divided into its sections, storing the versions
of
> the
> > sections by Plone version applicability, then having one single user
> manual
> > with a menu choice of which version to view. The sections shown for
a
> view
> > of the user manual would be a best fit for the requested version,
> > accordingly. With each Plone release, sections would need to be
> > marked/updated. This is really how it should be done. Advice and
ideas
> are
> > appreciated.
>
> Interesting. Any thoughts on how we could do this in PHC?
> SteveM, thoughts?
>
>
> One attractive possibility is to maintain the user manual in
> > straight python and directories/docs/images on the filesystem.
>
> eh, not too hot on this idea. Makes contributing that much harder for
> those who don't know python.
>
-------------- next part --------------
An HTML attachment was scrubbed...

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

Message: 2
Date: Sat, 20 Dec 2008 12:18:14 -0600
From: "JoAnna Springsteen" <[email protected]>
Subject: Re: [Plone-docs] Plone 3.2 User Manual Update
To: "Jeff Pittman" <[email protected]>
Cc: "[email protected]"
	<[email protected]>,	Paul Everitt
<[email protected]>
Message-ID:
	<34501d7e0812201018n793e84f6hda271923b3a5928e-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
Content-Type: text/plain; charset=ISO-8859-1

On Sat, Dec 20, 2008 at 11:38 AM, Jeff Pittman <[email protected]>
wrote:
> Also, at a recent sprint, there was an exploration of automation for
screen
> captures for the user manual and other documentation needs.

Yup. Seems like we've been talking about this since the PSU symposium.
I know Paul Everitt had thoughts on how this could be done too.
Not sure if anything ever came of it though.
Would still be interested in hearing how we could accomplish this
without making it hugely complicated.



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

Message: 3
Date: Sat, 20 Dec 2008 12:26:32 -0600
From: "JoAnna Springsteen" <[email protected]>
Subject: Re: [Plone-docs] Plone 3.2 User Manual Update
To: "Jeff Pittman" <[email protected]>
Cc: "[email protected]"
	<[email protected]>
Message-ID:
	<34501d7e0812201026j5537c307h77c140c20a78438b-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
Content-Type: text/plain; charset=ISO-8859-1

On Sat, Dec 20, 2008 at 12:18 PM, Jeff Pittman <[email protected]>
wrote:
> Love the python.
>
> The sections would be stored in svn?, so contributing wouldn't be a
problem,
> eh?

We're trying really really hard to adjust PHC to make it easier to
manage our docs. The editors aren't real thrilled on the idea of
managing docs in yet another way.
Love it or hate it, PHC is here to stay. Of course, SteveM and others
are working very hard to make PHC kinder and friendlier and more
usable. And I believe they are still taking ideas.

This is the direction we are pursuing for formal docs. Let's think of
a way to do this within PHC.



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

Message: 4
Date: Sat, 20 Dec 2008 12:31:28 -0600
From: "Jeff Pittman" <[email protected]>
Subject: Re: [Plone-docs] Plone 3.2 User Manual Update
To: "JoAnna Springsteen" <[email protected]>
Cc: "[email protected]"
	<[email protected]>,	Paul Everitt
<[email protected]>
Message-ID:
	<1253ecbd0812201031m60aba47ap45be363b5423dff3-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
Content-Type: text/plain; charset="iso-8859-1"

The screen capture facility would be accomplished, I imagine, with a
driver
script operating on hooks (special codes) in the docs to drive the
browser
and captures -- or such a script developed in parallel.

Regarding complication of such a system, having a driver system in
python is
not a bad thing -- we are a python house, ultimately. :)

And, I wouldn't want us to shy away from innovation.  Such an approach
inherently requires an intelligent system, for which we are fully
capable of
designing and maintaining.  It would be like other complicated python
scripts I use on the command line -- a chore to build, but once they
work,
they become workhorse utilities.

Jeff

Jeff Pittman
http://www.geojeff.org


On Sat, Dec 20, 2008 at 12:18 PM, JoAnna Springsteen
<[email protected]>wrote:

> On Sat, Dec 20, 2008 at 11:38 AM, Jeff Pittman <[email protected]>
> wrote:
> > Also, at a recent sprint, there was an exploration of automation for
> screen
> > captures for the user manual and other documentation needs.
>
> Yup. Seems like we've been talking about this since the PSU symposium.
> I know Paul Everitt had thoughts on how this could be done too.
> Not sure if anything ever came of it though.
> Would still be interested in hearing how we could accomplish this
> without making it hugely complicated.
>
-------------- next part --------------
An HTML attachment was scrubbed...

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

Message: 5
Date: Sat, 20 Dec 2008 10:25:56 -0800
From: "Steve McMahon" <[email protected]>
Subject: Re: [Plone-docs] Plone 3.2 User Manual Update
To: "[email protected]"
	<[email protected]>
Message-ID:
	<26a908b50812201025h4e742229y139707740656a340-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
Content-Type: text/plain; charset=ISO-8859-1

There are supposed to be few to no user interface changes in the 3.x
series. In fact, the P3 Framework Team has turned down several PLIPs
in order to avoid making any changes that would invalidate end-user
documentation.

3.2 will require some installation documentation, as it obsoletes the
old tarball installation method. But, that's pretty much it.

So, I'd rather just have one 3.x manual. If though, you'd like to have
a working copy to change in place, then use to replace the older 3.x
manual, that's fine.

Steve

On Sat, Dec 20, 2008 at 2:50 AM, Jeff Pittman <[email protected]>
wrote:
> I am interested in working on a Plone 3.2 version of the user manual.
One
> way of doing it is to copy the 3.0 version (manual content type in
PHC),
> then modifying in place for 3.2. That's what we did when we made a 3.0
> manual from the 2.5 version. Steve, iirc, you did something special to
copy
> it?
>
> New screen captures, updated text, and replacement screencasts will be
> needed.
>
> The screencasts are stored outside of the manual, on Plone's media
server. I
> have Screenflow for making screencasts, and I think these are really
> important to weave into the user manual, even more than we did for the
> previous versions. Sam, I've been meaning to ask you about your
current
> screencast-making routine -- Veda mentioned jing...
>
> Jeff
>
> Jeff Pittman
> http://www.geojeff.org
>
>
------------------------------------------------------------------------
------
>
> _______________________________________________
> Plone-docs mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/plone-docs
>
>



-- 

Steve McMahon
Reid-McMahon, LLC
steve-HR5nRXif9uVv8oa/[email protected]
[email protected]



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

Message: 6
Date: Sat, 20 Dec 2008 10:41:17 -0800
From: "Steve McMahon" <[email protected]>
Subject: Re: [Plone-docs] Plone 3.2 User Manual Update
To: "[email protected]"
	<[email protected]>
Message-ID:
	<26a908b50812201041i73c25d4dx876d46c573b1d7fd-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
Content-Type: text/plain; charset=ISO-8859-1

Automating the screenshots is totally cool. It's the editable prose
that we'd like to keep inside the CMS, where it can be worked on by
prose writers who aren't necessarily comfortable with svn and
particular markup schemes.

On Sat, Dec 20, 2008 at 10:31 AM, Jeff Pittman <[email protected]>
wrote:
> The screen capture facility would be accomplished, I imagine, with a
driver
> script operating on hooks (special codes) in the docs to drive the
browser
> and captures -- or such a script developed in parallel.
>
> Regarding complication of such a system, having a driver system in
python is
> not a bad thing -- we are a python house, ultimately. :)
>
> And, I wouldn't want us to shy away from innovation.  Such an approach
> inherently requires an intelligent system, for which we are fully
capable of
> designing and maintaining.  It would be like other complicated python
> scripts I use on the command line -- a chore to build, but once they
work,
> they become workhorse utilities.
>
> Jeff
>
> Jeff Pittman
> http://www.geojeff.org
>
>
> On Sat, Dec 20, 2008 at 12:18 PM, JoAnna Springsteen
<[email protected]>
> wrote:
>>
>> On Sat, Dec 20, 2008 at 11:38 AM, Jeff Pittman <[email protected]>
>> wrote:
>> > Also, at a recent sprint, there was an exploration of automation
for
>> > screen
>> > captures for the user manual and other documentation needs.
>>
>> Yup. Seems like we've been talking about this since the PSU
symposium.
>> I know Paul Everitt had thoughts on how this could be done too.
>> Not sure if anything ever came of it though.
>> Would still be interested in hearing how we could accomplish this
>> without making it hugely complicated.
>
>
>
------------------------------------------------------------------------
------
>
> _______________________________________________
> Plone-docs mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/plone-docs
>
>



-- 

Steve McMahon
Reid-McMahon, LLC
steve-HR5nRXif9uVv8oa/[email protected]
[email protected]



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

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


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

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


End of Plone-docs Digest, Vol 31, Issue 9
*****************************************

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