Update and restructure documentation in Frontend and Design System sites for v4 and v5

[vanitabarrett]

What

We need to decide what v5 documentation is needed and how we want to continue providing documentation for users who will stay on v4.0.0 of GOV.UK Frontend

Why

See our browser proposal for more details.

Who needs to work on this

Developers; Designers; Tech Writer

Who needs to review this

Developers; Designers; Tech Writer

Done when

Infrastructure - git

Beta Give feedback

1. Create a seperate folder for v4 documentation
2. Update v4 links, for example, all links to v4 need to prefixed with `/v4

Infrastructure - hosting

Beta Give feedback

1. Spike technical approach for hosting v4 in a subfolder govuk-frontend-docs#346
   +0
   

   
2. Create new section in the Frontend site for the v4 documentation
3. Migrate v4 documentation to new section and add appropriate banners informing readers this is an old version
4. Keep track of PaaS decommissioning in case we need to migrate all sites to a different platform.

Content

Beta Give feedback

1. 'Current events' content (e.g. roadmap, community pages) has been removed from the v4 docs or otherwise noted that it may be out of date
2. Draft v5 content changes for frontend and design system sites
3. Create a new page highlighting v5 differences and how to migrate to v5 govuk-frontend-docs#315
   documentation +1
4. Announce upcoming v5.0 changes for digital team managers and leaders govuk-frontend-docs#321
   4 of 5
   documentation +1
   
5. Define and create new content needed for v5.0.0 of GOV.UK Frontend govuk-frontend-docs#311
   documentation +1
   
6. Update Internet Explorer documentation govuk-frontend-docs#188
   documentation +1
   
7. Document new JavaScript API in Frontend docs govuk-frontend#3974
   javascript +1
8. Update Design System site content for v5 changes #2993
   documentation +1
   
9. Check that content that needs to link to v4 links to v4 docs, and similarly for v5 #3356
   +0

Tasks

Beta Give feedback

1. Update JavaScript content in Frontend for v5 changes govuk-frontend-docs#341
   documentation +1
   
2. Update Design System site content for v5 changes #2993
   documentation +1
   
3. Add guidance on graded browser support govuk-frontend-docs#340
   documentation +1
   

   
4. Add guidance on staying up to date govuk-frontend-docs#339
   documentation +1
   
5. Create a new page highlighting v5 differences and how to migrate to v5 govuk-frontend-docs#315
   documentation +1
6. Prepare v5 release notes govuk-frontend#4181
   documentation +1
   
7. Update README to reflect changes to browser support govuk-frontend#4368
   documentation +1
   
8. Prepare comms material for V5 release govuk-frontend#4369
   🚀 release +1
   

[trang-erskine]

@vanitabarrett @EoinShaughnessy @Ciandelle , Claire (new tech writer) and I had a chat

There are 2 sets of documentation we are concerned about 1) Frontend docs and 2) Design System website

In the past, when we've done breaking changes, we no longer actively support previous version and tell our users to upgrade to the latest version. However, for this next breaking change, we will support (outlined in the proposal) V4 for 12 months. This means that we may want to make older documentation semi-permanently available.

1. Frontend docs
   In the past, we don't keep a copy of previous versions of Frontend docs. The group decided that it's possible for V4 content to live alongside V5 as there are less changes and the audience (developers) are familiar with the concept of having different versions. However, we need to investigate to confirm this will work and what content might need changing. (E.g https://frontend.design-system.service.gov.uk/supporting-ie8/)

2. Design System website
   In the past, we give users who asked for previous versions of the website a Netlify link (https://v3--govuk-design-system-preview.netlify.app/) that is a copy of the Design System website before the next breaking change. This was given on request, rather than publicised. For the V5 release, we need to make a V4 content easier to access.

We suspect that using Netlify link, link previous times, will not be sufficient as users may not trust it. We may also bump into an issue similar to hosting prototypes on Heroku and it being flagged by Google as 'insecure'

We are concerned that users will be confused about whether they are looking at V4 or V5 content on the website. Is the 'archive banner' we have on v3 docs enough?

We're not sure if there are specific content we need to write about V4 or V5. For example from the proposal, V4 will remain compliant with WCAG 2.1 and not later versions and V5 will eventually become compliant with WCAG 2.2 and any future versions. Are we obligated to help users on V4 to understand the differences and how they might stay compliant?

Tasks

• Investigate if V4 content can run alongside V5 content on Frontend docs
• We know where and how we will signpost users to V4 of the docs (e.g linking from various places on the website, github repos, frontend docs, comms to users)
• Users can easier differentiate between whether they are reading V4 content or V5 content of the Design System website
• We know what additional content we need to be added specifically for V4 version and V5 version of the Design System Website
• We know what additional content we need to be added specifically for V4 version and V5 version of Frontend Docs
• Investigate what options we have with PaaS (e.g as a subdomain of the Design System or somewhere else)
• Decide where to host V4 version of Design System website

[claireashworth]

Re-added failed beta task list.

[36degrees]

I think this is done.