#9324: Use Amberjack to offer guided help for first-time users
---------------------------+------------------------------------------------
Reporter: limi | Owner: massimo
Type: PLIP | Status: new
Priority: n/a | Milestone: 4.1
Component: Documentation | Resolution:
Keywords: |
---------------------------+------------------------------------------------
Changes (by massimo):
* owner: sknox => massimo
* status: assigned => new
Old description:
> '''Proposer:''' Alexander Limi[[BR]]
> '''Seconder:''' Nate Aune[[BR]]
> [[BR]]
> == Motivation ==
> Getting started after installing Plone is currently one of our main user
> experience problems. The "what do I do now?" question isn't really
> answered, and people find it hard to get started with basic content
> editing, publishing, and other simple tasks.
>
> There's an LGPLed product out there that uses a JS overlay to guide you
> through operating any web site without interfering with the original
> HTML, called [http://www.amberjack.org Amberjack]. We propose using
> Amberjack to create these guided tours for people new to Plone.
>
> There are lots of great things about Amberjack, some of which are:
> * Uses standard HTML files for the guided help, which means we can apply
> ZPT for dynamic substitutions where needed, and most importantly: use
> i18n tags to have the guided help in the user's own language!
> * Doesn't rely on the Plone theme in any way, so works equally well on
> sites that have another theme applied.
> * Can fill in information for the user, so they don't have to type in
> stuff manually to test things — and lets you split up something like an
> edit form into several steps that are done one at a time.
>
> For more information about Amberjack, please have a look at:
> * [http://www.slideshare.net/Jazkarta/amberjack-lightning-talk Nate's
> lightning talk about collective.amberjack] — this has much more info on
> the technical implementation and capabilities, recommended before you
> read the rest of this PLIP!
> * The [http://www.amberjack.org Amberjack web site]
>
> == Assumptions ==
> In general, I'd say that this package shouldn't be in core Plone as such,
> but probably be standard issue in the installers. People building their
> own setups via buildout shouldn't have to worry about removing this from
> every setup they create. On the other hand, adding it in should be a
> simple matter of adding the relevant egg(s) to buildout.
>
> I'm also aware that this PLIP is a bit thin on the implementer side at
> the moment (because of time pressure), but the upside of this effort is
> that if it doesn't happen, it's not part of the core Plone package, but
> only ships with installers. If it doesn't materialize in time, we can
> always add it in later, similar to how we do incremental improvements to
> the installer itself.
>
> I still hope this PLIP is worth serious consideration, especially since
> the implementation is already available as a standalone product, and it
> solves one of the fundamental user experience issues we have currently.
>
> == Proposal & Implementation ==
> The major part of this project already exists in the collective.amberjack
> product. In addition to some refinements to the existing product, the
> majority of the implementation would consist of:
> * Getting feedback from experienced integrators and trainers on which
> scripts to include
> * Write up concise, short, to-the-point HTML documents walking people
> through these use cases
> * Get these documents ready and annotated with i18n tags in time for the
> translators to complete translated tours for their language
>
> == Deliverables ==
> * A refined version of collective.amberjack that fixes some of the minor
> Amberjack UI issues
> * A collection of walkthrough scripts implemented in the HTML format
> that Amberjack uses
> * Fully marked up with i18n tags, it can be translated into our shipping
> languages
> * Translations to the majority of our shipping languages
>
> == Risks ==
> * It puts a slightly larger burden on our translators, as there will be
> more strings to translate.
> * Special care has to be taken to make sure we don't intermingle this
> product in a way that affects Plone core. Shouldn't be a problem, but is
> worth noting. :)
>
> == Participants ==
> The current module owners from the Sorrento '09 and Bolzano '08 sprints
> are:
>
> * Massimo
> * Stefano
> * Harito
> * Giorgio
> * Daniel
>
> I am still in the process of checking if any of them are willing to
> shepherd this into the Plone 4 installers.
>
> On the "which things should we teach people to do" side of things, I
> volunteer myself to help identify where to focus our efforts — I will
> probably mostly be collecting feedback from people like Joel Burton and
> Jon Stahl, since these people have extensive experience with what people
> are struggling with, and common use cases that they teach first-time
> users.
>
> From the i18n side, I have solicited help from Vincent Fretin — the
> current i18n team leader — to get feedback and, if possible, assistance
> with the i18n side of the effort.
>
> == Progress ==
> collective.amberjack already exists in the Collective, and is as far as I
> know in a working state. They also have a couple of scripts for it. I
> expect us to do some work on some of the UI, since it has a few warts
> from the Amberjack side of things (not related to the Plone integration,
> which is great).
>
> Relevant URLs:
> * Buildout:
> http://svn.plone.org/svn/collective/collective.amberjack.buildout/trunk/
> * Project page: http://www.openplans.org/projects/collectiveamberjack
> /project-home
New description:
'''Proposer:''' Alexander Limi[[BR]]
'''Seconder:''' Nate Aune[[BR]]
[[BR]]
== Motivation ==
Getting started after installing Plone is currently one of our main user
experience problems. The "what do I do now?" question isn't really
answered, and people find it hard to get started with basic content
editing, publishing, and other simple tasks.
There's an LGPLed product out there that uses a JS overlay to guide you
through operating any web site without interfering with the original HTML,
called [http://www.amberjack.org Amberjack]. We propose using Amberjack to
create these guided tours for people new to Plone.
There are lots of great things about Amberjack, some of which are:
* Uses standard HTML files for the guided help, which means we can apply
ZPT for dynamic substitutions where needed, and most importantly: use i18n
tags to have the guided help in the user's own language!
* Doesn't rely on the Plone theme in any way, so works equally well on
sites that have another theme applied.
* Can fill in information for the user, so they don't have to type in
stuff manually to test things — and lets you split up something like an
edit form into several steps that are done one at a time.
For more information about Amberjack, please have a look at:
* the project's [http://www.coactivate.org/projects/collectiveamberjack
/project-home homepage]
* [http://www.slideshare.net/Jazkarta/amberjack-lightning-talk Nate's
lightning talk about collective.amberjack] — this has much more info on
the technical implementation and capabilities, recommended before you read
the rest of this PLIP!
* The [http://www.amberjack.org Amberjack web site]
== Assumptions ==
In general, I'd say that this package shouldn't be in core Plone as such,
but probably be standard issue in the installers. People building their
own setups via buildout shouldn't have to worry about removing this from
every setup they create. On the other hand, adding it in should be a
simple matter of adding the relevant egg(s) to buildout.
I'm also aware that this PLIP is a bit thin on the implementer side at the
moment (because of time pressure), but the upside of this effort is that
if it doesn't happen, it's not part of the core Plone package, but only
ships with installers. If it doesn't materialize in time, we can always
add it in later, similar to how we do incremental improvements to the
installer itself.
I still hope this PLIP is worth serious consideration, especially since
the implementation is already available as a standalone product, and it
solves one of the fundamental user experience issues we have currently.
== Proposal & Implementation ==
The major part of this project already exists in the collective.amberjack
product. In addition to some refinements to the existing product, the
majority of the implementation would consist of:
* Getting feedback from experienced integrators and trainers on which
scripts to include
* Write up concise, short, to-the-point HTML documents walking people
through these use cases
* Get these documents ready and annotated with i18n tags in time for the
translators to complete translated tours for their language
== Deliverables ==
* A refined version of collective.amberjack that fixes some of the minor
Amberjack UI issues
* A collection of walkthrough scripts implemented in the HTML format that
Amberjack uses
* Fully marked up with i18n tags, it can be translated into our shipping
languages
* Translations to the majority of our shipping languages
== Risks ==
* It puts a slightly larger burden on our translators, as there will be
more strings to translate.
* Special care has to be taken to make sure we don't intermingle this
product in a way that affects Plone core. Shouldn't be a problem, but is
worth noting. :)
== Participants ==
The current module owners from the Sorrento '09/'10, Budapest '09 and
Bolzano '08 sprints are:
* massimo
* Stefano
* Harito
* Giorgio
* Daniel
* amleczko
* fdelia
* Mirco
I am still in the process of checking if any of them are willing to
shepherd this into the Plone 4 installers.
On the "which things should we teach people to do" side of things, I
volunteer myself to help identify where to focus our efforts — I will
probably mostly be collecting feedback from people like Joel Burton and
Jon Stahl, since these people have extensive experience with what people
are struggling with, and common use cases that they teach first-time
users.
From the i18n side, I have solicited help from Vincent Fretin — the
current i18n team leader — to get feedback and, if possible, assistance
with the i18n side of the effort.
== Progress ==
collective.amberjack already exists in the Collective, and is as far as I
know in a working state. They also have a couple of scripts for it. I
expect us to do some work on some of the UI, since it has a few warts from
the Amberjack side of things (not related to the Plone integration, which
is great).
We already have 12 tours and a promising [http://www.vimeo.com/12198138
windmill integration] (thanks to Andrea Benetti)
Relevant URLs:
* Buildout:
http://svn.plone.org/svn/collective/collective.amberjack.buildout/trunk/
* Project page: http://www.coactivate.org/projects/collectiveamberjack
/project-home
* Bugtracking: https://launchpad.net/collective.amberjack
--
Comment:
what we're planning to do for Plone 4.1 is to complete the 1.1
collective.amberjack's release.
it's described in
https://launchpad.net/collective.amberjack/+milestone/1.1a
all the blueprints are in
https://blueprints.launchpad.net/collective.amberjack
--
Ticket URL: <http://dev.plone.org/plone/ticket/9324#comment:31>
Plone <http://plone.org>
Plone Content Management System
_______________________________________________
PLIP-Advisories mailing list
plip-advisor...@lists.plone.org
http://lists.plone.org/mailman/listinfo/plip-advisories
