Let user choose which version of Notify docs they want to view by CrystalPea · Pull Request #5235 · alphagov/notifications-admin

CrystalPea · 2024-10-01T17:10:53Z

Let user choose which version of Notify docs they want to view - when sending them a link to a particular section in the docs.

What work has been done here

a page added where platform admin can submit a link to a section within Notify docs
when that that is submitted, a page is produced that can be sent to the service user
The service user who goes to that page can choose which language version they want to see our docs for
Upon selecting the language and submitting their selection, they are taken to the docs of their choice, to the section that our tech support wanted to share

✨

Why do this work

We do this as often when sending service users links to a section in the docs, we don't know which of our clients they use, if any.

Notes

I also included "Any is fine" option to choose, for users who aren't very technical, but would still like to see the docs.
It might be hard for these users to choose from a list of options they are not familiar with. Hence, I provided a "comfort" option for them. Selecting this will take them to rest API docs.

Screenshots

Link to new flow - only visible to Platform Admins

Enter URL

Choose language version of the docs

It allows user to enter an URL.

…tribute.

in those docs.

…OST request

When sending them a link to a particular section in the docs. We do this as often when sending service users links to a section in the docs, we don't know which of our clients they use, if any. I also included "Any is fine" option to choose, for users who aren't very technical, but would still like to see the docs. It might be hard for these users to choose from a list of options they are not familiar with. Hence, I provided a "comfort" option for them. Selecting this will take them to rest API docs.

The link is only visible to platform admins.

saimaghafoor · 2024-10-03T15:37:05Z

app/templates/views/guidance/using-notify/api-documentation.html

+        target="_blank" rel="noopener">
+        Send a link to docs section
+      </a>


Suggested change

target="_blank" rel="noopener">

Send a link to docs section

</a>

target="_blank" rel="noopener">

Send a link to the Notify API documentation

</a>

If this is for platform admins, do we need to specify ‘Notify’?

Can we just say the API documentation instead?

saimaghafoor · 2024-10-03T15:38:58Z

app/templates/views/guidance/using-notify/api-documentation-section.html

+
+{# Used by the content_template.html layout, prefixes the "navigation" accessible name #}
+{% set navigation_label_prefix = 'Using Notify' %}
+{% set page_title = "Send a link to an API docs section" %}


Suggested change

{% set page_title = "Send a link to an API docs section" %}

{% set page_title = "Send a link to the Notify API documentation" %}

If this is for platform admins, do we need to specify ‘Notify’?

Can we just say the API documentation instead?

app/main/forms.py

joybytes · 2024-10-03T16:58:40Z

app/main/forms.py

+        if parsed_url.hostname == "docs.notifications.service.gov.uk" and parsed_url.fragment:
+            return parsed_url
+        else:
+            raise ValidationError("Must be a valid https URL, pointing to a section within the GOV.UK Notify API docs.")


feel free to ignore

Suggested change

raise ValidationError("Must be a valid https URL, pointing to a section within the GOV.UK Notify API docs.")

raise ValidationError("The URL must point to a specific section in the GOV.UK Notify API docs, and start with 'https://docs.notifications.service.gov.uk'.")

Nice one, I will add this to code (and tests)

We can probably be a little more consistent with our existing validation errors.

Suggested change

raise ValidationError("Must be a valid https URL, pointing to a section within the GOV.UK Notify API docs.")

raise ValidationError("Enter a URL in the correct format, beginning https://docs.notifications.service.gov.uk")

Suggested change

raise ValidationError("Must be a valid https URL, pointing to a section within the GOV.UK Notify API docs.")

raise ValidationError("Enter a URL beginning https://docs.notifications.service.gov.uk")

app/main/views/index.py

klssmith · 2024-10-04T14:27:08Z

app/main/views/index.py

    )


+@main.route("/using-notify/api-documentation/section", methods=["GET", "POST"])


Should this either be platform admin only or have the @hide_from_search_engines decorator? There's nothing sensitive on the page, but it might be confusing to people if they come across it

Good idea to hide it from search engines 🙌🏼

klssmith · 2024-10-04T14:54:31Z

You've probably already seen this but not all the headings are consistent, so that might need to be looked at before this could be merged. No major differences, just things like #get-a-pdf-for-a-letter-notification vs #get-a-pdf-for-a-letter

CrystalPea · 2024-10-04T15:46:34Z

@klssmith yeah, I thought they probably aren't - we have upcoming work on the team to get API docs more in line with one another - maybe we could start with making the headers match 🙌🏼 . What do you think @saimaghafoor ? Could be a good goal for first pass over the docs?

quis · 2024-10-08T12:59:27Z

agree that we should fix the mismatched headings (comparison tool)
don’t think we need radio buttons here – the choices could just be links
I don’t like adding additional, platform-admin-only elements (the link) to user-facing pages because it confuses people on support about what users can/cannot see

quis · 2024-10-08T13:00:37Z

As an interim step could we automatically validate that the header exists in all the docs before generating the link?

karlchillmaid · 2024-10-16T20:13:48Z

app/main/forms.py

+            ("rest-api", "Rest API"),
+            ("rest-api", "Any is fine"),
+        ],
+        thing="a language version of GOV.UK Notify's API docs",


Apart from the REST API documentation, we refer to these as ‘client libraries’ elsewhere.

karlchillmaid · 2024-10-16T20:15:53Z

app/templates/views/guidance/using-notify/api-documentation-section-choose-docs.html

+
+{# Used by the content_template.html layout, prefixes the "navigation" accessible name #}
+{% set navigation_label_prefix = 'Using Notify' %}
+{% set page_title = "You have been sent a link to GOV.UK Notify API documentation" %}


Suggested change

{% set page_title = "You have been sent a link to GOV.UK Notify API documentation" %}

{% set page_title = "You have been sent a link to the GOV.UK Notify API documentation" %}

karlchillmaid · 2024-10-16T20:18:54Z

app/templates/views/guidance/using-notify/api-documentation-section.html

+{% block content_column_content %}
+
+<h1 class="heading-large">{{page_title}}</h1>
+<p class="govuk-body">Below, copy paste the full URL for docs section you would like to send to a service user, and click "Submit".</p>


Suggested change

Below, copy paste the full URL for docs section you would like to send to a service user, and click "Submit".

Enter the full URL for a section of the API documentation and select Submit.

karlchillmaid · 2024-10-16T20:22:55Z

app/templates/views/guidance/using-notify/api-documentation-section.html

+<p class="govuk-body">Below, copy paste the full URL for docs section you would like to send to a service user, and click "Submit".</p>
+
+<p class="govuk-body">You will be taken to
+a landing page for that section. Send link to that page to your user, and they will be able to choose which language version they want to see.</p>


Suggested change

a landing page for that section. Send link to that page to your user, and they will be able to choose which language version they want to see.

a landing page for that section. Send the URL of that page to the user. When they open it in their browser, they’ll be able to choose a client library.

karlchillmaid · 2024-10-16T20:34:24Z

app/main/forms.py

+        super().__init__(section_tag=section_tag)
+
+    docs_version = GovukRadiosField(
+        "Which version of the docs would you like to view?",


Suggested change

"Which version of the docs would you like to view?",

"Choose a client library",

CrystalPea force-pushed the api-docs-sections-landing-page branch from f9b0d8a to 9addf91 Compare October 2, 2024 17:15

CrystalPea marked this pull request as ready for review October 3, 2024 10:55

CrystalPea changed the title ~~Api docs sections landing page~~ Let user choose which version of Notify docs they want to view Oct 3, 2024

CrystalPea force-pushed the api-docs-sections-landing-page branch 2 times, most recently from 8513197 to 62caaf8 Compare October 3, 2024 13:36

CrystalPea added 3 commits October 3, 2024 14:38

Add "Send user API docs section" page

812fd25

It allows user to enter an URL.

On POST, redirect to Choose Guidance Version page with section_tag at…

78a2dfa

…tribute.

Validate URL - must be a link to Notify docs taht goes to a section

3f77feb

in those docs.

CrystalPea force-pushed the api-docs-sections-landing-page branch from 62caaf8 to 5f2ef9e Compare October 3, 2024 13:38

CrystalPea added 4 commits October 3, 2024 14:46

Add page where user can choose version of docs to view section in

720318d

Pass the section tag in form's hidden field - so it's available for P…

cde01bf

…OST request

Link to send section flow from API Documentation guidance page

7c0e5a2

The link is only visible to platform admins.

CrystalPea force-pushed the api-docs-sections-landing-page branch from 5f2ef9e to 7c0e5a2 Compare October 3, 2024 13:47

saimaghafoor reviewed Oct 3, 2024

View reviewed changes

Fix navigation-related tests

bfe101b

joybytes reviewed Oct 3, 2024

View reviewed changes

app/main/forms.py Show resolved Hide resolved

joybytes reviewed Oct 3, 2024

View reviewed changes

app/main/views/index.py Show resolved Hide resolved

klssmith reviewed Oct 4, 2024

View reviewed changes

karlchillmaid reviewed Oct 16, 2024

View reviewed changes

Update page title and h1

585b795

karlchillmaid reviewed Oct 16, 2024

View reviewed changes

quis marked this pull request as draft December 9, 2025 11:34

	{% set page_title = "Send a link to an API docs section" %}
	{% set page_title = "Send a link to the Notify API documentation" %}

	raise ValidationError("Must be a valid https URL, pointing to a section within the GOV.UK Notify API docs.")
	raise ValidationError("The URL must point to a specific section in the GOV.UK Notify API docs, and start with 'https://docs.notifications.service.gov.uk'.")

	raise ValidationError("Must be a valid https URL, pointing to a section within the GOV.UK Notify API docs.")
	raise ValidationError("Enter a URL in the correct format, beginning https://docs.notifications.service.gov.uk")

	raise ValidationError("Must be a valid https URL, pointing to a section within the GOV.UK Notify API docs.")
	raise ValidationError("Enter a URL beginning https://docs.notifications.service.gov.uk")

		)


		@main.route("/using-notify/api-documentation/section", methods=["GET", "POST"])

	{% set page_title = "You have been sent a link to GOV.UK Notify API documentation" %}
	{% set page_title = "You have been sent a link to the GOV.UK Notify API documentation" %}

	<p class="govuk-body">Below, copy paste the full URL for docs section you would like to send to a service user, and click "Submit".</p>
	<p class="govuk-body">Enter the full URL for a section of the API documentation and select <b class="govuk-!-font-weight-bold">Submit</b>.</p>

	a landing page for that section. Send link to that page to your user, and they will be able to choose which language version they want to see.</p>
	a landing page for that section. Send the URL of that page to the user. When they open it in their browser, they’ll be able to choose a client library.</p>

	"Which version of the docs would you like to view?",
	"Choose a client library",

Conversation

CrystalPea commented Oct 1, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Let user choose which version of Notify docs they want to view - when sending them a link to a particular section in the docs.

What work has been done here

Why do this work

Notes

Screenshots

Link to new flow - only visible to Platform Admins

Enter URL

Choose language version of the docs

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

karlchillmaid Oct 16, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

klssmith commented Oct 4, 2024

Uh oh!

CrystalPea commented Oct 4, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

quis commented Oct 8, 2024

Uh oh!

quis commented Oct 8, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

karlchillmaid Oct 16, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

karlchillmaid Oct 16, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

CrystalPea commented Oct 1, 2024 •

edited

Loading

karlchillmaid Oct 16, 2024 •

edited

Loading

CrystalPea commented Oct 4, 2024 •

edited

Loading

karlchillmaid Oct 16, 2024 •

edited

Loading

karlchillmaid Oct 16, 2024 •

edited

Loading