Display guidance content snippets on issues details page

[CharliePatterson]

Context:

There are two types of guidance produced for data specifications:

• technical specifications, e.g. Article 4 directions, which defines the format for how Article 4 directions must be provided as data (a technical document)
• guidance for data providers, e.g. Article 4 directions, which provides a step-by-step guide for how to prepare data to meet the specifications (a user-facing document)

Guidance is more user-friendly than a technical specification and deliberately omits certain fields a data provider may not have to provide, for example, organisation which can be inferred from the organisation providing the data. They don’t need to provide it because the pipeline can add it.

Technical specifications can be produced automatically from the template for a technical specification and the data specification itself. However, guidance for data providers is currently hard-coded on the main planning.data.gov.uk website. This means user-facing guidance can sometimes be inconsistent with the technical specifications, and multiple pull requests need to be raised in order to make a small change. This has left data providers confused in the past, which means they don’t prepare or provide data until the inconsistency has been addressed.

It’s also not ideal that users need to navigate away from the Submit & Update service when preparing and checking data. Providing snippets of guidance inside the service, rather than on other pages, would reduce the interaction costs associated with navigating to another web page. It gives users information at the point they need it. Embedding guidance directly into the check tool minimises disruption and improves task focus.

Design / Prototype:

• Issues details page

Implementation detail:

• These content snippets should be dynamically pulled from a centralised source - ideally the data specification repository. The technical approach will be filled in following this spike.

Acceptance criteria:

• As a data provider, when I'm viewing the issues details page in the check tool (being built here), I'm able to see the relevant content snippet from the guidance, so that I can see the relevant piece of information in-situ, rather than having to navigate to the guidance to find it.
• Ensure that the snippet displayed is relevant to the specific issue type and field.

Error handling:

If it fails, and we can still link to the specific guidance page for that dataset, we should say:

How to fix this issue
Read the brownfield land guidance to help you fix the issue.

If it fails, and we're unable to link to the specific guidance page for that dataset, we should make it more generic and link to the overall guidance instead:

How to fix this issue
Check the guidance for help on how to fix the issue.

[DilwoarH]

Blocked until issue details page is done (#786)