Spike: Investigate how to move the user guide into the service

[teeceeas]

Objective
Explore the feasibility of integrating the user guide directly into the data catalogue service, ensuring that users can access relevant guidance seamlessly within the platform and it can still be updated easily.

Done When:
A summary of findings, including the best approach based on feasibility, usability, and maintenance is completed.

[LavMatt]

Options explored

The issue of having the user guide external to the service has been raised and suggested it might better reside within the Find MoJ data (fmd) service. This spike has explored and evaluated some potential options to migrate our external user guide into fmd.

I’ve looked at the following approaches:

• Open source content management systems (CMS), such as Django CMS and Wagtail.
• Embedding the external user guide within fmd
• Parsing and rendering the raw markdown files within our own Django gov styled html templates.

[LavMatt]

Open source CMS

Looked at Django CMS and Wagtail

They look broadly similar in their offerings but would both add a lot of complexity to our application.

I looked into Wagtail in a little more detail as reading around it suggested it was more suited to developer led user guides with Django CMS being tailored more towards a non technical audience.

I began attempting to implement a couple of pages as a PoC but it was kind of tricky and i aborted as to not spend too much time on this. You can get a flavour of the complexity added by taking a look at https://medium.com/@shahraizali300/integrate-wagtail-into-existing-django-project-django-blog-app-168f2db6cdfe and https://docs.wagtail.org/en/stable/getting_started/integrating_into_django.html#

It still wants to push you towards using a wagtail admin screen and creating and storing all your content via django models and backend database tables

These seem much more suited to content that’s intended to be a bit more dynamic and allow user interaction.

Pros:

• Would potentially create quite a slick looking user guide.

Cons:

• Would be a lot of work relative to what's gained.
• High level of complexity compared to our current user guide.

A CMS basically seems like overkill for our user case, which is a static user guide. My opinion is it would take a fair bit of time and add a lot of complexity plus maintenance burden compared to what we have with the user guide as is.

[LavMatt]

Embedding the user guide in find moj data

I tested this out as a potentially very quick solution after seeing the embedding of the quicksight dashboard work pretty nicely.

Since our user guide is publicly available we are able to embed it into a page in find moj data with minimal code, e.g.

 <iframe
     style="width: 100%; height: 710px; overflow: auto;"
     src="https://user-guide.find-moj-data.service.justice.gov.uk/"
     allowfullscreen="true">
 </iframe>

However this approach means we repeat the headers from the user guide within the iframe window in fmd and for this purpose it isn’t really suitable.

Can improve a bit by adding the below code to application.js in the userguide code

if (window.location.search.includes("embed=true")) {
    document.querySelector('header').style.display = 'none';
 }

And adding ?embed=true to the url used in the iframe removes the header, e.g.

But this becomes difficult to implement once links within the user guide are clicked and other sections are visited because the links are not inclusive of ?embed=true.

It might be interesting to explore the development of the user guide docs template so that it can serve an embedding URL for specific allowed domains. Giving a look similar to the above for all pages in the user guide. However, I haven't looked into whether this is possible, especially since I believe these documentation templates are hosted on GitHub Pages.

But this becomes difficult to implement once links within the user guide are clicked and other sections are visited because the links are not inclusive of ?embed=true.

It might be interesting to explore the development of the user guide docs template so that it can serve an embedding URL for specific allowed domains. Giving a look similar to the above for all pages in the user guide. However, I haven't looked into whether this is possible, especially since I believe these documentation templates are hosted on GitHub Pages.

Pros:

• Doesn’t add additional complexity to find moj data.
• Could be useful for other teams wanting to follow a similar pattern and embed a user guide within their own application.
• User guide consistent in format and familiarity with other technical user guides.

Cons:

• Needs further a spike to explore how the template could be developed and may not be possible to implement.
• Links that were to other domains inside the user guide would need to open in a new tab or they wouldn’t work.
• Users might be confused and send a link to a specific part of the user guide but would just arrive at the embedded page.

[LavMatt]

Render markdown user guide pages within FMD

The user guide is currently a collection of markdown files. These are good because they are easy to create, edit and quickly anticipate how the page will look, even if done by a non technical team member.

This option is to lift those markdown files into the fmd codebase and then we write some code to parse and render the markdown in one of our gov.uk styled html templates.

I mocked up something relatively quickly as a PoC. See draft PR #1354

Further work would be needed to implement the user guide search functionality and make the side menu more akin to the current user guide.

Pros:

• Get to keep the raw user guide content in markdown files
• Not overly complex

Cons:

• Does still require some additional development and add some complexity to the fmd app.