Integrate Evergreen documentation into the Staff Client

[Blake GH]

We're looking at ways to integrate "How to"'s directly onto the staff client pages. We'd like to see a little "question mark" icon or something like that on each staff client page. When clicked, the interface would retrieve the related documentation for that staff client function and display it for the user. This documentation should be able to include:

Text
Images
Videos

We'd like this documentation to be allowed to be overridden down the org unit tree. The consortium-level documentation would be the default documentation. Each system and branch can override the documentation. This will require a new back-end interface for editing the documentation. Giving staff the permission to do so at different org unit levels.

Right now, I'm planning on introducing this feature. I'm thinking I'll write a new perl API on the back-end and hook it up to the front-end. That should facilitate delivery of the the documentation to the browser. I'll integrate a WYSIWYG on the staff client for ease of editing the docs. We'll store the documentation in the database. It'll most likely need it's own PG schema.

If you have more ideas on this, please reply!

[Stephanie Leary (stephanieleary)]

The introduction of a WYSIWYG would introduce a world of accessibility issues disproportionate to the overall benefit of the editing feature. I would strongly advise that we start with a simple textarea that supports either Markdown or a limited set of HTML tags rather than a full rich text editor with an interactive toolbar.

Even the toggle button to show/hide the documentation is more complicated than it sounds. See https://inclusive-components.design/tooltips-toggletips/ for a discussion of the UI and accessibility issues.

Do you envision having this documentation available per screen/route, or per component? I would support a help link that would appear in the navigation menu or the footer, or both. In fact I really want us to introduce a footer with links to screen-specific documentation!

I would be very wary of scattering help icons throughout the interface; that would require a lot of attention to usability and keyboard workflow, and I'm not sure we as a community have the capacity to manage that well right now.

What is the plan for localization?

[Jason Boyer (jboyer)]

Rather than building a CMS into the ILS we could do something like this:

Build structured URLS with the Eg version and a page's "documentation name" (like local-admin, acq-search, checkout, etc.) and add an OUS to hold the hostname of a documentation server that has the full set of documentation. Then these ? buttons can just build the links similar to this: https://(docs-hostname-ous)/egdocs/3.11/local-admin-print-templates . (Maybe the page names are built somehow by inspecting the Angular Route that it's using, I dunno)

The OUS could be defaulted to a community server so there's a shared baseline (of documentation we already have, though not organized in such a way that this is an easy thing to do). This could be changed for the consortium to a local server with a copy of the docs that is heavily customized. As for OU-level overrides, They *could* supply their own hostname if they wanted to do a lot of work, or a list of documentation overrides could be kept in a new interface. If a page has an override at this OU that's where the link takes you, or it will fall back to the normal OUS host + autobuilt url.

The main issue I see with *any* approach is that it will be a very large documentation rebuild / reorg project to make them usable by any system that's not artisanal hand-crafted links on each page or telling each installation that they now have a blank slate they can begin filling at their leisure.

[John Amundson (jamundson)]

I think this is a great idea.

We have a ton of local documentation that could benefit from page-specific links.

I'd like to see this manifest as a link or button on each page and then an Admin interface where you control if the link appears on x page and where the link goes to. The Admin interface could associate links with an org so that they only appear on workstations owned by the org, defaulting back to CONS links if no specific org-links are set.

I think many of us already have on our own documentation databases or use the community docs, so I'm not sure if it would be necessary to store any documentation directly in the Evergreen database, just have the ability to link out to somewhere else.

[Blake GH (bmagic)]

My first inclination was the link idea. Where Evergreen would store a key pair.

"Page" -> "Doc URL".

And that could be branch overridden. Maybe that's what we start with. It would be much less complicated, that's for sure.

The natural next thought is: Evergreen has a fairly mature set of documentation already, can we incorporate that?

And the answer is: not really.

Here's why:

Like Jason said, our community documentation isn't structured to be page specific. Without changing our documentation (I don't think we should), the best we can do is link a doc that is "close" to the interface that you're on. I think we can agree that wouldn't be ideal. It could lead to confusion. And the confusion is probably worse than not having a document in the first place.

So we're back to forcing each institution to create their own web-exposed documentation. Which is asking a lot I think. Making this feature fall flat.

This train of thought brings me back to providing a method for recording the page-specific documentation directly in Evergreen.

Stephanie:
From a code stand point, I figured the ? button would be in the header/nav strip (or footer for that matter, but the footer would be less visible). As opposed to the body of the page. I came to that conclusion because I figured it'd be sweet to have one chunk of code that handles that button, regardless of the page. The JS behind can check back with the server on page load, looking for matching documentation, if it doesn't find one, then the button wouldn't be presented.

I'm open to ideas on how to present the actual documentation on the page. I've used several different websites that have "help/tips" for each page. And I've seen it manifest itself in a "sidebar" down the left or right side of the page. I personally don't prefer that. I gravitate towards a more full screen approach. If the user wants to see the documentation, then give it to them in full. It could be a new tab or window, but a new tab/window can be confusing to some folks. They've lost the page they were on. I'm in favor of a page overlay. Maybe grey out the page and plop a slightly smaller frame into view. Making it apparent that the page that you are on is still "behind" and you can "click away" or click on the "X" button on the documentation frame to close it out.

Thinking about this presentation layer might inform us on the documentation itself. If it was a link to an external site, then we'd have to iframe it or scrape it and re-present it in our own <div>. That's messy. The iframe approach would be less error prone. I don't love either. Which further supports the idea of baking the documentation directly into the Evergreen database.

If we bake it in, we could seed the documentation table with some portion of the documentation that we already have. As a starting point for people. During upgrade, we'd have some SQL to fill out the table the best we can with what we have. Either in html format or something else.

So now we're thinking about format. All of the aforementioned train of thought brought me to WYSIWYG. Because HTML format gives the staff the freedom to basically do anything. Accessibility concerns came to mind but I ...