Ticket #9324 (closed PLIP: wontfix)
Use Amberjack to offer guided help for first-time users
Reported by: | limi | Owned by: | massimo |
---|---|---|---|
Priority: | n/a | Milestone: | Future |
Component: | Documentation | Version: | |
Keywords: | Cc: | dukebody, vincentfretin, sam@…, jluvsu2, plip-advisories@…, grahamperrin@…, massimo, amleczko |
Description (last modified by massimo) (diff)
Proposer: Alexander Limi
Seconder: Nate Aune
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 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 homepage
- 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 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 windmill integration (thanks to Andrea Benetti)
Relevant URLs:
Change History
comment:2 Changed 7 years ago by dukebody
- Cc dukebody added
Great! I volunteer on reviewing the HTML guides and testing in general.
comment:3 Changed 7 years ago by vincentfretin
- Cc vincentfretin added
This product is awesome. You can count on me for the i18n part.
comment:4 Changed 7 years ago by pupq
Sure; I'll be happy to work with Jon to write some high-level scripts of the features that could stand to be surfaced and explained well.
comment:5 follow-up: ↓ 6 Changed 7 years ago by davisagli
- Cc sam@… added
Great PLIP, provided you can find the implementer(s). I nominate Sam Knox to help with the task of identifying what things to teach (assuming he's willing) ... he has put together a great series of basic Plone training articles for ONE/Northwest clients and was excited about the possibilities of Amberjack when I showed him Nate's lightning talk.
comment:6 in reply to: ↑ 5 Changed 7 years ago by sknox
Replying to davisagli:
Great PLIP, provided you can find the implementer(s). I nominate Sam Knox to help with the task of identifying what things to teach (assuming he's willing) ... he has put together a great series of basic Plone training articles for ONE/Northwest clients and was excited about the possibilities of Amberjack when I showed him Nate's lightning talk.
I'd totally be interested in this. I was really impressed with the Amberjack demo and I think it may represent the next generation of "tutorial videos". In my estimation, the core set of basic skills would be something along the lines of the Quick Start Tutorial on LearnPlone.Org
I could also see tackling some more advanced topics such as how to create new sections on the site, collections, portlet management, etc.
comment:7 follow-up: ↓ 9 Changed 7 years ago by jluvsu2
While I was impressed with the demonstrations of Amberjack I have seen on the web and at the Penn State Symposium, I have a few concerns about adding this to standard issue installers.
First, including Amberjack adds additional overhead to the installers, tacking on more installation items where the complexity of the installs is already a common complaint among newbies - identified as the primary audience for this. Would we want to do this? Or would it make sense to create a training/evaluation installer which would be aimed specifically at this audience and not run the risk of adding problems to the beginning users' experience with Plone. More advanced developers would have no need for this and would probably prefer that this was not included in the installers or buildout at all. Is it safe to assume that the majority of use cases for production ready Plone sites would never want to use this?
However we choose to do this, if we do, I think it should be purely optional. The problem with that is that saying it can be added to a Buildout really means you are not doing it as a tool to offer guided help to first-time users. First time users are not the ones you would expect to be installing Plone via Buildout, or even installing it at all. Is there another more serviceable use-case for site tours? What about a demo.plone.org that uses Amberjack and the pre-recorded tours so that users don't have to download anything at all? I'd definitely back a demo.plone.org that uses Amberjack.
Are we aware of any impact on the stability, upgradability and browser accessibility of Plone sites as a result of introducing Amberjack here? Just trying the demo tour on their website, you'll notice that the popup window blocks access to everything on the page except for the tour content and the "X" to close the tour. For a truly new user, this could be confusing - or make them think the Plone site has actually crashed.
From a documentation and setup perspective, online tours and demonstration videos are more difficult for average users to grasp than simple, well-written documentation. There is a reason why most software setup links don't just point to videos on YouTube. If something goes wrong with your Plone site, you can't see the videos - and therefore they are pretty much useless from a help perspective. Many users also want a printed copy of a step-by-step process - something they won't get with a video or a overlayed tutorial.
My most serious concern with this issue is the potential it has for drawing resources away from already resource-strapped documentation efforts. Since the proposal here is for this technology to replace/supplement training for Plone newbies, it is important that it be viewed in the context of the overall documentation efforts. The documentation editors team and the framework team should work together to fully support this option if they see it as being as important or more important than other documentation efforts. As it stands, this has not yet been done. Further more, the documentation team is low on resources and is trying to finish up a large initiative right now. We should add this to the documentation team roadmap and form a working team to review the technology and make a recommendation on how best to incorporate it. Since several people have already volunteered support, forming a team shouldn't be a problem. I am simply worried that resources are spread thin already.
Finally, since Plone 5 is going to be a more radical, game-changing release that will require a large scale rewrite of existing documentation, wouldn't it make sense to target that release instead of Plone 4, which will require updating but not wholesale replacement of large sections of our documentation? This would give us more time to test, target and implement Amberjack as a possible delivery method for documentation instead of just an add-on largely duplicating the web-based documentation we already have.
comment:9 in reply to: ↑ 7 Changed 7 years ago by pupq
Replying to jluvsu2:
First, including Amberjack adds additional overhead to the installers, tacking on more installation items where the complexity of the installs is already a common complaint among newbies
I'm not sure that adding a package to Plone that gets installed for you, as part of Plone, adds to the complexity for new users.
However we choose to do this, if we do, I think it should be purely optional.
I think many people would find Amberjack useful, and wouldn't even know to look for it if it weren't exposed to discovery. I also think that people who have existing Plone sites or help systems may not want it to always be installed.
A reasonable way to solve this might be something like: it ships with Plone (it's quite small), and gets added as part of the extension profile for Plone. You can uninstall it if you'd like to not include it. Or we include it as a package but its profile is not installed by default.
Finally, since Plone 5 is going to be a more radical, game-changing release that will require a large scale rewrite of existing documentation, wouldn't it make sense to target that release instead of Plone 4, which will require updating but not wholesale replacement of large sections of our documentation? This would give us more time to test, target and implement Amberjack as a possible delivery method for documentation instead of just an add-on largely duplicating the web-based documentation we already have.
I disagree here; there are *plenty* of features in Plone 4 that users need help with. And if Plone 5 does constitute a dramatic change to our UI, as planned, our having some real history with writing and getting feedback about TTW teaching would be very useful.
I think this inclusion is +1 for integrators; having tools that lets them start their docs for users is a nice deal. In fact, every time I've described Amerjack to classes since the Symposium, the response has been "awesome!"
comment:10 Changed 7 years ago by hillsy
My occasional £0.02... If it's packaged as part of the installer and as long as it's obvious how to turn this off, it's probably not going to add a lot of complexity for new users.
OTOH people do use the installers for production systems (whether they should or not, isn't in scope here). So it does need to be possible to turn it off.
As an integrator, I don't really buy the idea that it helps integrators. Except for simple installs integrators need to write their own docs eventually. For site-specific customisations etc. And if anyone suggests we can now write them as as Amberjack tutorials, I'll hit them with my stop-changing-everything-all-the-time stick ;-)
Mainly, this PLIP seems to help OOTB Plone users. Which is probably a valid - albeit specific and limited - use case.
comment:11 Changed 7 years ago by erikrose
- Owner limi deleted
Clearing Owner field of 4.0 PLIPs so we can use it to mean "implementor". (Many of these owners were automatically assigned from choosing a Component that had a default owner.)
comment:12 Changed 7 years ago by alecm
+1
We need to make it very easy to turn this on or off on new sites, and I think the quality of the included documentation will be the primary factor when reviewing the "code" for this PLIP.
comment:14 Changed 7 years ago by MatthewWilkes
I think this one will be risky, in terms of time, adding lots of workload to the i18n teams, possibly annoying old-school users, etc. I'll sit on the fence, I think.
FWT Vote: +0
comment:15 Changed 7 years ago by rossp
I'd like to see this in an add-on available for 4.0 and maybe included in 4.x once vetted.
FWT vote: -1
comment:16 Changed 7 years ago by davisagli
FWT vote: +1, assuming this is only bundled with the installer but not an explicit dependency of Plone.
comment:17 follow-up: ↓ 19 Changed 7 years ago by calvinhp
FWT Vote: -0, but I could be swayed to a +1 if we were to only include this functionality as an extended install option that was off by default in the standard installers a la the firefox installers option to install the developer plugins. I don't see this as a core part of Plone, but more of an installer "feature".
comment:18 Changed 7 years ago by raphael
FWT Vote: -0
I don't get why that should be in core
comment:19 in reply to: ↑ 17 Changed 7 years ago by limi
Replying to calvinhp:
FWT Vote: -0, but I could be swayed to a +1 if we were to only include this functionality as an extended install option that was off by default in the standard installers a la the firefox installers option to install the developer plugins.
That's what I meant by optional install, sorry if I was unclear on that.
comment:20 Changed 7 years ago by erikrose
Saw Nate's lightning talk and think AJ has a lot of potential! Reminds me of Apple Guide a lot. If we ever end up with any kind of online help system (e.g. you're in the middle of a task and get confused, so you hit some Help icon someplace), I could see a context-sensitive selection of AJ tours being offered.
That said, I like the AJ-on-demo.plone.org idea. We can link to it from the default front page and see whether people find it useful. If they do, I could see AJ becoming the engine that drives the context-sensitive help I fantasize about above. But until then, I don't see a gain from installing this on people's local machines (though I'm always open to enlightenment).
My FWT vote is -1 for shipping it with Plone, but I would love to see it done on demo.plone.org and linked from the default front page.
comment:21 Changed 7 years ago by raphael
Revising my FWT vote to +1 after further discussion and given that this isn't pulled in per default in regular installs
comment:22 Changed 7 years ago by erikrose
Replying to erikrose:
But until then, I don't see a gain from installing this on people's local machines (though I'm always open to enlightenment).
The gain is that some tours may involve editing content, which people presumably wouldn't be able to do on demo.plone.org scalably.
Changing my FWT vote to +1, since we can always tear this back out without breaking much backward compatibility.
comment:26 Changed 7 years ago by vincentfretin
comment:28 Changed 7 years ago by massimo
comment:30 Changed 6 years ago by limi
- Milestone changed from 4.x to 4.1
As far as I know, we're going to try to get this in for 4.1.
comment:31 Changed 6 years ago by massimo
- Owner changed from sknox to massimo
- Status changed from assigned to new
- Description modified (diff)
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
comment:32 Changed 6 years ago by esteele
Your PLIP has been accepted for consideration for Plone 4.1.
Framework Team voting on this PLIP was: Alec +1 Craig +1 Elizabeth +1 Laurence +1 Martijn +1 Matthew +1 Rob +1 Ross --
The initial implementation deadline for your PLIP is October 1st, 2010. The Framework Team would certainly appreciate you finishing beforehand so that they may begin evaluating it as soon as possible. Announce its readiness here once your implementation is ready for review.
comment:33 Changed 6 years ago by amleczko
comment:34 Changed 5 years ago by massimo
we released the 1.1 version ( https://launchpad.net/collective.amberjack/+milestone/1.1)
We also added a brief description in the plips directory: http://svn.plone.org/svn/plone/buildouts/plone-coredev/branches/4.1/plips/plip9324-collective.amberjack.txt
let me know if something more is needed
comment:35 Changed 5 years ago by timo
There seems to be a problem with the current buildout:
./bin/buildout -c plips/plip9324-collective.amberjack.cfg
timo@rudolf:~/workspace/plone/plone-4.1-coredev$ ./bin/instance fg 2010-11-27 13:59:05 INFO ZServer HTTP server started at Sat Nov 27 13:59:05 2010 Hostname: 0.0.0.0 Port: 8080 /home/timo/.buildout/eggs/Products.CMFCore-2.2.2-py2.6.egg/Products/CMFCore/FSObject.py:21: DeprecationWarning: RoleManager is deprecated. RoleManager is no longer part of AccessControl, please depend on Zope2 and import from OFS.role or use the new minimal RoleManager class from AccessControl.rolemanager. from AccessControl.Role import RoleManager 2010-11-27 13:59:08 INFO ZODB.blob (5508) Blob directory `/home/timo/workspace/plone/plone-4.1-coredev/plips/../var/blobstorage` is unused and has no layout marker set. Selected `bushy` layout. 2010-11-27 13:59:08 INFO ZODB.blob (5508) Blob temporary directory '/home/timo/workspace/plone/plone-4.1-coredev/plips/../var/blobstorage/tmp' does not exist. Created new directory. 2010-11-27 13:59:08 WARNING ZODB.blob (5508) Blob dir /home/timo/workspace/plone/plone-4.1-coredev/var/blobstorage/ has insecure mode setting Traceback (most recent call last): File "/home/timo/.buildout/eggs/Zope2-2.13.0-py2.6.egg/Zope2/Startup/run.py", line 72, in <module> run() File "/home/timo/.buildout/eggs/Zope2-2.13.0-py2.6.egg/Zope2/Startup/run.py", line 21, in run starter.prepare() File "/home/timo/.buildout/eggs/Zope2-2.13.0-py2.6.egg/Zope2/Startup/__init__.py", line 86, in prepare self.startZope() File "/home/timo/.buildout/eggs/Zope2-2.13.0-py2.6.egg/Zope2/Startup/__init__.py", line 259, in startZope Zope2.startup() File "/home/timo/.buildout/eggs/Zope2-2.13.0-py2.6.egg/Zope2/__init__.py", line 47, in startup _startup() File "/home/timo/.buildout/eggs/Zope2-2.13.0-py2.6.egg/Zope2/App/startup.py", line 118, in startup load_zcml() File "/home/timo/.buildout/eggs/Zope2-2.13.0-py2.6.egg/Zope2/App/startup.py", line 52, in load_zcml load_site() File "/home/timo/.buildout/eggs/Zope2-2.13.0-py2.6.egg/Zope2/App/zcml.py", line 46, in load_site _context = xmlconfig.file(site_zcml) File "/home/timo/.buildout/eggs/zope.configuration-3.7.2-py2.6.egg/zope/configuration/xmlconfig.py", line 653, in file context.execute_actions() File "/home/timo/.buildout/eggs/zope.configuration-3.7.2-py2.6.egg/zope/configuration/config.py", line 606, in execute_actions callable(*args, **kw) File "/home/timo/.buildout/eggs/AccessControl-2.13.3-py2.6-linux-i686.egg/AccessControl/security.py", line 165, in protectClass permission = getUtility(IPermission, name=permission_id) File "/home/timo/.buildout/eggs/zope.component-3.9.5-py2.6.egg/zope/component/_api.py", line 169, in getUtility raise ComponentLookupError(interface, name) zope.configuration.config.ConfigurationExecutionError: <class 'zope.component.interfaces.ComponentLookupError'>: (<InterfaceClass zope.security.interfaces.IPermission>, 'cmf.ManagePortal') in: File "/home/timo/workspace/plone/plone-4.1-coredev/src/collective.amberjack.core/collective/amberjack/core/configure.zcml", line 84.2-89.8 <browser:page name="aj-controlpanel" for="Products.CMFPlone.interfaces.IPloneSiteRoot" class=".controlpanel.AJControlPanelForm" permission="cmf.ManagePortal" />
comment:36 Changed 5 years ago by alecm
comment:37 Changed 5 years ago by massimo
fixed the problem reported by timo.
what should I do with the alec's review? he suggested several things, should I reply here?
comment:38 Changed 5 years ago by alecm
Discussion of the reviews belongs either here in Trac or on the Framework Team mailing list. Note that Matthew Wilkes has also written a review of the PLIP, which is available in SVN.
comment:39 Changed 5 years ago by massimo
Thanks Alec and Matthew for the work done! I moved all the remarks made here: https://launchpad.net/collective.amberjack/+milestone/1.1.1
some of the are already set to someone that will fix them, others need to be deeply discussed. I would ask both Alec and Matthew to check them and tell me their thoughts.
it seems to me that the most important issues are:
- https://bugs.launchpad.net/collective.amberjack/+bug/697359 (see reply)
- https://bugs.launchpad.net/collective.amberjack/+bug/697347 (see reply)
- https://bugs.launchpad.net/collective.amberjack/+bug/697338 (we need to do more)
- https://bugs.launchpad.net/collective.amberjack/+bug/697335 (we probably need help from documentation team)
comment:40 Changed 5 years ago by alecm
Thanks for taking the time to file issues based on the reviews and beginning discussion there. It's great to see you've already fixed some of the technical issues and are thinking about the broader issues. Having high quality tutorials is the goal of this PLIP though, so issues regarding the tutorial appropriateness and quality will need to be weighed very heavily.
comment:42 Changed 5 years ago by rossp
- Status changed from new to closed
- Resolution set to wontfix
PLEASE READ THIS AND RE-OPEN VALID PLIPS!
As we launch the new PLIP process we'd like to see which PLIPs:
- are still appropriate/needed
- still have owners/proposers/champions
- still have available implementers
If this PLIP should still be considered for future releases of Plone please do re-open this ticket and assign an appropriate milestone. If it should be considered for the next release of Plone, use the 4.2 milestone. Also be sure to update the PLIP description, requester, owner, etc. and include a comment detailing recent progress and new plans. We will use all these details in the new continuous PLIP process.