Set up first example of embedded help

[cecilia-donnelly]

@brainwane discussed the need for embedded (tooltip-type) help in #195.

• In-app context-sensitive help
  This depends on the frontend libraries and frameworks we use; James suggested it would be nice if we could in some way reuse stuff from a central knowledge base. Read the Docs content embedding via JavaScript via JavaScript might be something to consider.

When a user is completing a form on a page (for example), we should offer a tooltip for each field that describes what we expect the content of that field to look like. For example, a tooltip for "NPI" might say something like "National Provider Identifier" and describe where a provider can get an NPI.

The to-do's for this issue are:

1. Should we use a framework like the RTD one Sumana mentioned? If so, which one? We'd like to reuse text in the tooltips and standalone documentation, and keep them up to date with each other.
2. Create a tooltip for a field.

[brainwane]

I started work on this by getting familiar with setting up a brand-new Read the Docs project with a few placeholder pages of documentation, which I've been able to do; next I'll start a branch with the PSM that includes some documents that build to Read the Docs, and uses the JavaScript content embedding approach.

[brainwane]

Further thought, investigation, and conversation with @jasonaowen later:

• I don't want to use JavaScript to embed content in the PSM from ReadTheDocs because that introduces a network dependency; what if the user's behind a firewall, for instance?
• I want to use ReStructuredText for user help docs, at least at first, because Sphinx works well with it (building it into HTML) and the ReadTheDocs workflow works well with Sphinx. Any new build step, though, will have to also include a Gradle change.
• Whatever templating system we use (sticking with JSP, moving to Jinja, or other), we'll have to implement some way for the user to hover/click/select the embedded/inline/tooltip/hover/contextual help. And that's going to be its own kind of tough thing, and it'd be good to figure out how to do that first (and submit a PR for it first).

So I'm going to try this:

1. hand-write a small HTML file with "What's an NPI?" help text in psm-app/cms-web/WebContent/WEB-INF/pages/
2. figure out how to get a JSP file to transclude this HTML file as hover text on a relevant <span> or a similar element, e.g., the NPI chunk of psm-app/cms-web/WebContent/WEB-INF/pages/provider/enrollment/steps/pageTemplates/default/personal_information.jsp [and submit this as a PR]
3. write an .rst file containing that "What's an NPI?" help text
4. get Sphinx to build that to an HTML file that lives in a directory in psm-app/cms-web/WebContent/WEB-INF/pages/
5. get personal_information.jsp to transclude that file

[brainwane]

Progress!

[brainwane]

I'd like to make my contextual help more helpful than an unstyled title element can be. For instance, in the NPI contextual help, I'd like to actually provide a clickable link to https://nppes.cms.hhs.gov/ .

So I am going to poke around a little and see if there is any existing tooling for providing contextual anything anywhere within the templates.

[brainwane]

I did some searching and I can't find any existing tooling within the PSM for providing richer contextual help.

• An element like <details> would be awesome, but Internet Explorer doesn't support it. (This investigation led to me filing Specify OSes and browsers we support #298.)
• Rich tooltip solutions (1, 2, 3) basically always require JavaScript/CSS beyond my current fluency or, like, a special Java library.

So here's my current plan:

• For pure abbreviations, the <abbr> tag will probably be my go-to.
• We're going to use plaintext for the contextual help for now.
• I'll write a sample admin doc, which will be longer than a piece of embedded help would be, and then start on the Sphinx-and-RTD side of this issue.

[jasonaowen]

An element like <details> would be awesome, but Internet Explorer doesn't support it.

If IE/Edge support is important, and we want to use <details>, we may be able to use a polyfill. There are several JavaScript libraries available on GitHub, although none of them seem like a clear winner to me.

For the sake of evaluating compatibility, we're currently using jquery-1.7.1.

[brainwane]

I'm working on the assumption that the list of admin help topics I made in #195 (comment) is reasonable. I'm working on "Which enrollment information the provider or service agent can modify or delete, and which enrollment information the service admin can modify or delete" for now. (I recognize that the precise content there will change over time; I'm picking this topic because it's something I can test locally and it's for service admins.)

[brainwane]

I have just found a tooltip implementation in the PSM, in the organizational enrollment workflow, in psm-app/cms-web/WebContent/WEB-INF/pages/provider/enrollment/steps/pageTemplates/default/ownership_information.jsp, where there's a question mark character next to "Type" that, when clicked, causes a pop-up with definitions: