Crafting Embedded Help in Hostile Application Environments


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

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

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

I’m really liking the idea of EPPO for Embedded Help.

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.

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.

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.

My users are a mixture of bookmakers, client support staff, credit, and finance teams.

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.

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.

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.

Using the xi:include function would make this relatively easy to do,