govuk-prototype-kit
govuk-prototype-kit copied to clipboard
alphagov
Investigate how to support users on v12 and older when documentation is updated to v13
What
When we make changes to the documentation support v13, this will confuse users on v12 or older. Investigate solutions to this.
Why
Some users will still be on v12 or older and need documentation that works for their version.
Who needs to work on this
- Interaction designer
- Content designer
- Developers
Who needs to review this
- Interaction designer
- Content designer
- Developers
Done when
- [x] We have an idea of how to support users on v12 and older with documentation
- [x] We have identified where new documentation is needed for v13
- [x] We have priorities documentation work
2/9 Meeting outcomes Options: • maintain separate documentation for v12 and v13 • make it available on website and link from Kit (linking to relevant version) • archive v12 version online (like DS has done) @joelanman
Considerations: • using descriptive naming for versions (maybe month, year) • potential user research on new guidance
Next step: • start drafting v13 now to help with deciding which option is best, focus on differences/new things https://docs.google.com/document/d/1vOx9xyynxQtHuIKnrGTHoVFnAMT6XwZCQF0G_8qsy68/edit
Notes on the Design System's archiving (in Google docs as its not really public) https://docs.google.com/document/d/1sFwUfnOzTfbLnjLOha5Thficj_otPPp73Cvl42iMGsk/edit#
The Design System team have a similar piece of work in their backlog: https://github.com/alphagov/govuk-frontend-docs/issues/189
1st step - release beta v13. After that Nora & Joe can start the process of the solutions.
Internal notes: https://docs.google.com/document/d/1l_7lfIa8ZMpRF_4g0NwSkSshr71tP7xw1_IHftoDcjI/edit#
Internal design: https://www.figma.com/file/sWnqT4u4uup91TuTe9T3tp/GOV.UK-Prototype-Kit-information?node-id=163%3A2
We're leaning towards having a version of the v12 docs hosted alongside the v13 docs, in some way (see option 4 in https://docs.google.com/document/d/1l_7lfIa8ZMpRF_4g0NwSkSshr71tP7xw1_IHftoDcjI/edit#).
We need to figure out how to implement this technically; one option is to just split the docs repo (again), having a v12 repo and a v13 repo, but I worry this will just increase the rate of bitrot of the docs code and eventually leave us open to security issues.
@lfdebrux to look at alternative options.
At a high level there are two options:
- A: Run the v12 docs and v13 docs apps with different code
- B: Run the v12 docs and v13 docs apps with the same code
There are lots of nuances in how either option A or B is achieved, but I think this way of looking at the question highlights the most important considerations.
Note that to some extent these options are loosely coupled to the decision as to whether we want the different versions of docs accessible at the same domain or not, i.e.
- X: govuk-prototype-kit--{version}.herokuapps.com/docs, or
- Y: govuk-prototype-kit.herokuapps.com/{version}/docs
Both option A and option B support either X or Y, although some combinations are easier.
Regardless of details, there are some general pros and cons, as follows:
A: Run the v12 docs and v13 docs apps with different code
Pros: easier initially, we can keep hosting the v12 docs in the same way, and base the v13 docs off of a copy of the v12 docs.
Cons: requires extra effort to keep the two codebases from diverging, for instance if we want to simplify the currently complex code to run the app, or need to make security updates. Additionally extra work is needed to be able to have the docs at different paths at the same domain (option Y). There is also likely to be an additional cost associated with an extra Heroku app ($7.99 a month).
B: Run the v12 docs and v13 docs apps with the same code
Pros: We have less code to maintain. Easier to have docs at different paths at same domain (option Y), and no need to have extra Heroku app. We can have more flexibility with how we present different versions of docs and move from one version to another.
Cons: More work initially, we will need to make some modifications to the app and duplicate content within the repo. There is also a possibly greater risk of confusion by editors. It may be more difficult to keep v12 docs looking the same as they do now in future.
@joelanman @nataliecarey are there any pros/cons missing do you think?
@lfdebrux thanks! I think you covered most of it
We can have more flexibility with how we present different versions of docs and move from one version to another.
Can you explain this one a bit more? Not sure I follow
My main concern with keeping them in the same codebase is, we'd like to completely redesign docs in future, but not have to worry about changing the old docs. The situation that seems closest to me is that of the old Elements site vs the new Design System site - an archive available to those who need it
@lfdebrux thanks! I think you covered most of it
We can have more flexibility with how we present different versions of docs and move from one version to another.
Can you explain this one a bit more? Not sure I follow
For instance, if we want the version number in the header, or the About link in the header to still be present but always go to the latest version, or to cut out the index page completely for the v12 docs, these things will be easier with a shared codebase.
My main concern with keeping them in the same codebase is, we'd like to completely redesign docs in future, but not have to worry about changing the old docs. The situation that seems closest to me is that of the old Elements site vs the new Design System site - an archive available to those who need it
I don't think either option precludes the possibility of completely redesigning the docs in future.
There is also a possibly greater risk of confusion by editors
This is my other concern - to explain, when I edit a page I normally search for it, and in the same codebase, multiple versions of the same file will come up
@ruthhammond has decided we should go with option B, although keeping the option to split out the v12 docs in future, and keeping the v12 docs in a separate folder which isn't touched very often:
We will run the v12 docs and the v13 docs with the same code v12 docs will be maintained quietly so they effectively become an archive, but with banners and a few flags at key points directing users to update to v13 Any more significant changes will be considered on a case by case basis
I will write up tickets to make this work happen.
Followup ticket: https://github.com/alphagov/govuk-prototype-kit-docs/issues/59