Challenge 25 - Integrated support documentation

[jwagemann]

Challenge 25 - Integrated support documentation

Stream 2 - Web development for weather, climate and atmosphere

Goal

To build a 'software style' help system/framework which can be plugged into the ECMWF web applications (apps) with a single, common line of code. Once the code is added to an app, a user will be able to click a link in the app's 'Help' menu and a popup/lightbox will open and display relevant support content fetched from Confluence (which is where the support content is hosted and maintained).

Mentors and skills

• Mentors: Helen Setchell, Helene Blanchonet, Cihan Sahin
• Skills required:
  • Confluence and Jira APIs, node server, javascript, react, css, html, content security (auth and tokens)
  • Editorial skills or understanding of content and content structures would be a distinct advantage

---

Challenge description

Why do we need a solution
To improve the user experience we would like users to be able to access context-sensitive help from within the web application (app) they are currently engaged with, without having to leave the app.

Currently, users of our apps must access support documentation by clicking through to Confluence via the Help link in each app. This takes the user away from their task within the app; they end up in a part of the ECMWF web which doesn't share the same navigation as the app and there is no guaranteed way back to the app from the documentation. Moving between the app and the documentation introduces the risk that the user loses their authentication session or app settings, or gets lost on our web, causing them to have to start again.

By providing the support content within the app, the user will more easily find and immediately use it to help them complete their task. This should reduce the need to raise a support ticket and wait for a response.

What could be the solution
We will start with the ecCharts app as a pilot as it has a limited audience and help content, and then extend the framework solution to the chart catalogue and/or the data catalogues as time allows (or in future projects).
The current setup is that support content is hosted in Atlassian Confluence for which there is an API. Some content may be protected and API calls must reflect the current user's authorisations.
Apps (ecCharts, the chart browser, and the data portals) are written on a Django framework and output dynamic HTML pages within the standard ECMWF template.

It should be possible to enable the help popup/lightbox in a web app with a single line of javascript (or similar), similarly to how google tag manager is added to pages. All variables should be handled outside the web app by the popup system/framework. E.g. for each app the app URL would determine the Confluence content to be included in that app's help system.

Another potential feature to investigate will be a documentation feedback system, e.g. "did this help?" at the bottom of each page. This would integrate either with the Confluence page like or comment feature, or with the Jira ticketing system / Support Portal.

Consideration to be given to:

• how this works overall with the current support portal user journey
• responsiveness, e.g. how it works on mobile
• caching the support content so that if Confluence is unavailable, the apps help system continues to work.