Crafting Embedded Help in Hostile Application Environments


#1

I’ve just set up a Middleman site that will publish AsciiDoc source as help topics

[9:23]
the content is then rysynced over to a directory on the app webroot where a script url-matches the embedded help page based on the php page name

[9:28]
Because the app was not designed to support Embedded Help, I’m having a tough time working out how to chunk the content.

[9:28]
I’m really liking the idea of EPPO for Embedded Help.

[9:29]
But because I don’t have the ability to deep link to elements of the UI, I’m finding myself moving away from EPPO and writing what amounts to a mini Users Guide for each primary page node in the UI.

[9:30]
There’s a page called finalizer.php. I can write a landing page called finalizer.adoc which will build to finalizer.html and get loaded by the script.

[9:32]
But do I then chunk it down to fields and atomize the content? Or do I write more of a User Guide narrative for the page, describing the sub-tabs on the page (which I can’t discretely write a url-substituted page for), and describe some tasks my users can do.

[9:33]
My users are a mixture of bookmakers, client support staff, credit, and finance teams.

[9:37]
The main motivation for me doing this is that my users don’t really leave the app during their work day. We have Confluence, but they really dislike using it. I prefer to bring the user docs to where they spend the most time.

[9:40]
I’m hoping folks here can provide a different perspective here, because I’m at the point where I could go a multitude of ways, but I feel most of them will end up being a rod for my back.

[9:41]
I could chunk content based on UI elements:

  • fields
  • tabs
  • buttons
  • groups

Then use the root pages (finalizer.adoc) as the container for the chunked details.

[9:42]
Using the xi:include function would make this relatively easy to do,

[9:44]