How do you tell your users more about the application you're building?
How do you introduce them to a big and complex system?
Option 1: Write compelling documentation (1a: hope they'll find it, 1b: hope they'll read it)
Option 2: Add documentation to the page you're currently building (2a: hope they'll scroll to it, 2b: hope they're not patronized by the never changing documentation)
Option 3: Provide an unsuspicious place where additional documentation can be made available right on the page, that doesn't distract, but helps if needed.
I've chosen Option 3 - and now combined two previous proofs of concept into one generic way to document your pages. You might have heard about ControlPanel Documentation. That's a plugin that links matching documentation for many places in ControlPanel. And you might have heard about Audioguide. Remember your first steps in Liferay DXP or Liferay Portal? The first time you opened ControlPanel? Were you overwhelmed by all of the options? Here, having the documentation at your fingertips really helps.
With the combination of the two plugins, your documentation extends to all pages, where you can add not only unintrusive documentation, but also an audioguide that highlights individual elements on Liferay's UI. Wonder what that looks like?
The audioguide looks like this (you'll have to imagine the sound, or scroll down)
And the documentation "toast" brings in relevant documentation like this:
So, if you're interested in seeing more than 2 second loops, how it applies to general pages outside of Control Panel, and listen to some audio track: I've recorded a short demo - one with a generic audioguide on Widgetpages, one with an audioguide on UserManagement (in ControlPanel).
Find the sourcecode on github. The ControlPanel Documentation part is submitted to Marketplace (at the time of this writing) but not yet approved. The github repository contains more "documentation resolvers", e.g. some samples that you can use for general pages.
And, if you look at the DocumentationResolver interface, you'll see that your own custom extension is just an easy extension to the available system: Here you can provide content based on whatever criteria you like. Or use one of the samples that you can find in this quite simple project.
Now, you'll only need to create the content.
Image Credits: CC-by 2.0 Bill Smith