search

tpximpact / mhclg-oruk

OpenReferralUK
0 stars 0 forks source link

Handling multiple API versions in docs #19

Open gjhltn opened 1 week ago

gjhltn commented 1 week ago

I make no bones about it, the proposed solution here was v much inspired by the way Next.js handles a similar problem.

My plan would be - all of this a nice to have, not an essential or a promise! - to provide on-page UI to switch between documentation versions.

ie much like the top left of https://nextjs.org/docs/13

IMG_5557

(It might for some use cases be valuable to be able to view both at the same time side by side... but this doesn't really scale to more than two versions of the standard, so I don't think it is the most sustainable option for the future - I feel the option above - a toggle - is better in the case where we have multiple future versions of the standard to compare)

MikeThacker1 commented 1 week ago

Guy, I'm happy to defer to you and Laura on aspects of the UI. Just two points:

  1. we need to be very clear what version we're dealing with and how to switch. The latest version should be the default although many may reference the initial version at first
  2. this applies not just to the API but to the HSDS structure and many aspects of the guidance
gjhltn commented 1 week ago

V much agree that if you're not looking at the most current version that needs a very very clear banner to inform you that you're consulting legacy documentation.

As for guidance... that's not so clear to me. If we're offering guidance, I think there might be a decent argument that a part of that guidance ought to be 'use the latest version'?