search

alphagov / govuk-design-system

One place for service teams to find styles, components and patterns for designing government services.
https://www.gov.uk/design-system
MIT License
475 stars 226 forks source link

Design System docs are ahead of older versions of GOV.UK Frontend #1034

Open hannalaakso opened 4 years ago

hannalaakso commented 4 years ago

Users on pre GOV.UK Frontend v3.0.0 rely on finding the correct markup in the Design System website. However in some cases the Design System docs are ahead of those older versions.

edwardhorsford commented 4 years ago

My service is on v.2 of the design system, and realistically will be for the foreseeable future. It would be greatly helpful for the docs for these older versions to be readily available.

As it is, the docs update on day 1 of a new release, but on that day pretty much every service will be on an older version. Ideally they'd update quickly - but for those that don't, the docs are potentially inaccurate.

Related: I quite like how 11ty handles some of this - as well as offering versioned docs, it tags changes with release version so you know when something came in (also good for spotting things that might be new):

Screenshot 2019-08-28 at 12 36 33

In my recent use case, I was missing the old colours - I frequently visit the design system site to get the sass variable names for the colours. With v3 these changed, so I can't easily visually see the colours.

marthaboggins commented 4 years ago

Hey guys. First up, I know that things are complicated so this isn't a rant :)

I think the most important thing is to signpost a) what release is the latest (both proto and frontend) b) that a new release has come out c) if it is a breaking release

In essence, updating the proto kit is potentially a days work for me, especially if things break. So the decision to update is often delayed...more so by the lack of coms about updates.

I think this needs highlighting on the design system site or pinned on the Slack board. Somewhere obvious in big shouty letters. Somewhere like this page is a good start for those who are looking to update: https://govuk-prototype-kit.herokuapp.com/docs/install. But also something in the main design system site where the component examples are, especially if it is a breaking release. Some horrible shouty banner?!

Or at the very least a link to this page if it is too time consuming updating the site each time: https://github.com/alphagov/govuk-prototype-kit/releases

I also think the update instructions are missing something for checking the layout.html file for any new components.

Anyhoo my 2 pence. Thanks guys!

NickColley commented 4 years ago

Thanks for giving us this feedback,

In the meantime while we figure this out you can visit the documentation relating to version 2.0 with this link: https://5d39678d051df10008000ca6--govuk-design-system-preview.netlify.com/

hannalaakso commented 3 years ago

We should consider this in relation to Frontend 4.0.0.

m-green commented 3 years ago

Thank you for your contributions to this issue!

We've now discussed this as part of doing more to support users through new versions, and we're moving forward with the team actions below. We'll continue the work there and close this issue.

  1. Continue to develop releases in a way that aims to minimises breaking changes and the work needed to upgrade.
  2. Run a session on the team to familiarise team members with changes in v4.0.0 so they can effectively recognise issues with upgrading, and help through our support channels.
  3. From the above, develop an MVP internal document for team members ahead of v4.0.0, with expected issues and their solutions. We'll also use this (and our support form) to track how many users encounter each issue, so we can prioritise either adding user documentation on changes between versions or using different approaches for future versions.
  4. Audit the channels we have for communicating about updates and who's responsible for them, and whether we should add more comms channels to help with releases.
  5. Depending on the things we learn above, consider new Design Content content about staying up to date and summarising recent changes.
  6. Continue to create and send Netlify versions of earlier versions of the Design System and its documentation when we're asked for them, but add a clearer banner that they're out-of-date in case they're inadvertently distributed more widely.
trang-erskine commented 1 year ago

@claireashworth FYI on previous conversation about previous version of the Design System and other documentation. This will be even more relevant for V5.0.0

querkmachine commented 1 year ago

Since v2 we've started keeping an archive copy of the documentation online, so that developers still on those older versions have documentation available: v2 docs, v3 docs.

However, we only make these archives when major, breaking releases are made. This is still inconvenient for developers who are on older minor releases: for example, a team may still be using GOV.UK Frontend v4.0 but the only documentation currently available is for v4.4.

Some thoughts on possible resolutions: