Instructions for people who cannot install the prototype kit on their computers (Issue/70)

[paulmsmith]

This PR is to add instructions for using the NHS Prototype Kit with Github Codespaces which is intended as a viable option for people who cannot (or would prefer not to) install the prototype kit on their computers.

It is contingent on a separate PR being merged to the prototype kit for a devcontainer to enable this.

Get started page

Setup the prototype kit on GitHub Codespaces

Step 1 - Create a Codespace

Step 2 - Working with Codespaces

[paulmsmith]

All comments, feedback welcome. I'm not the best writer and squeezed this in between other work.

[anandamaryon1]

Looks great, I'll give it a proper review asap (maybe next week though) and try to follow the instructions. Thanks for this 👍

[vickytnz]

I've suggested some changes (I probably should have done a PR)

1. I think our usual protocol is to try and lead with the action and then go into the platform so something like 'Install and use the kit with your web browser'
2. I've tried to do a bit of tweaking of text
3. I'm not sure what the deal will be if people need to commit code as we don't have that exactly in the install

Getting started

Start page

Page 1

Page 2

[paulmsmith]

Do you have those changes in a branch @vickytnz? Just the type of feedback needed. I just whacked up an initial bunch of stuff to shape for the docs. :)

[vickytnz]

Do you have those changes in a branch @vickytnz? Just the type of feedback needed. I just whacked up an initial bunch of stuff to shape for the docs. :)

sorry it's pushed to this branch, I haven't quite figured out how to do review changes from my laptop yet 🙈

[paulmsmith]

Do you have those changes in a branch @vickytnz? Just the type of feedback needed. I just whacked up an initial bunch of stuff to shape for the docs. :)

sorry it's pushed to this branch, I haven't quite figured out how to do review changes from my laptop yet 🙈

Oh I see. Didn't spot that, no worries that's all good.

[vickytnz]

The one thing that I missed when doing some rewrites was the balance of 'you can do this' and 'you can do this and the prototype kit has been set up to make it easy for you'- I kinda wrote it for the first option without thinking about the second. It could be something as simple as a line about 'For this tutorial we are using Codespaces. This is because it is it popular and part of Github. The prototype has built-in functionality to make it easy to connect to Codespaces' or similar.

[anandamaryon1]

Followed along and seems to work nicely. 👍

Minor comments:

• Where we first mention Codespaces and Gitpod, perhaps we should link to information about them (landing pages)?
• The Codespaces billing is quite complicated, maybe we should give a simple explanation for it, e.g (assuming we're 2 cores?) you'll be limited to around 60 hours per month, so consider whether this is enough for your needs. - a bit tricky since that could change beyond our control…
• Same issue for Gitpod, which is I think, around 50 hours per month. (https://www.gitpod.io/docs/configure/billing)
• Step 1.1: repo link, we should call this NHS Prototype Kit repository rather than NHSUK, to align with other docs
• Step 1.4: a screenshot here could be helpful too, so that users can understand that what they're looking at is correct and that it's all 'done' and running, and ready for the next step (since it's quite a complex interface and takes time to run)
• Step 2: save changes, second para's second sentence missing a space "changes with GitHub.You can use"
• Should take a look at where this guide should be linked into from other bits of the docs, eg. link from 'install on an NHSE laptop' and the 'install guide', as an alternative method

Happy to make these changes myself if you prefer @paulmsmith

Need a review from @sarawilcox and then we'll be good to go.

[anandamaryon1]

And another thing… 😃

I did a test push and it went into the nhsuk-prototype-kit repo, rather than a fork/clone of it.

• So I think this guide is missing the step where you clone the repo to your own Github account, then open a Codespace there, not on the main repo.

[sarawilcox]

Hi @paulmsmith, I just had a go at this and I think it's good! I made a teeny tweak to capitalisation just to check how things work. I'll come back to this PR over the next few days to review the content fully. For now, I just wanted to get an idea how it works from a user's point of view.

It works very similarly to GitPod so I was familiar with this sort of set up but it will be completely new for some people, especially content designers.

I think Codespaces won't just be for people who can't install software. It's probably also good for people who don't have strong technical skills and are finding it difficult to install the prototype kit (or something like that).

I can see people creating a Codespace following this guide, but then getting stuck on the editing/working with Codespaces page. The page goes into saving changes, managing prototypes etc. But I suspect non-specialists will need more help getting started. Just knowing:

• what they should expect to see on their screen
• where to find the files they'll be working on (for most content designers, it'll be app/views)
• that you can change the HTML and it will update in the browser, so you can see your changes as you work

The page points people off to https://docs.github.com/en/codespaces/getting-started/quickstart. But I'm struggling to understand that page. It's quite technical and the examples are not the sort that content designers can relate to.

I think people will need more help saving their changes and committing back to GitHub. Don't know if it helps to take them through the few key commands that I use as a content designer:

• git status
• git add .
• git commit -m "...."
• git push
  And to suggest that they ask the dev or designer in their team for help if they're having problems.

I'll feedback more comments when I do a proper content review. I'm wondering if @LauraJD would like to have a go at this as someone completely new to using the kit in the browser.

[vickytnz]

PS for visibility more than anything - I've ported over the Github Desktop instructions from the GOV.UK Prototype Kit as I think we do need the examples of how for example to download someone else's repo.

Work is on #167

I don't think that it will block this ticket should it finish first but could be part of a wider reframing of some of the instructions just to better acknowledge that people are going to be working on other people's stuff as much as making their own.

EDIT: actually on review I think that maybe my code will help with some of @sarawilcox's comments about there being a bit of an air gap between the instructions and just getting started. Happy to join forces on this and look at it in the round (for example maybe working up the Github guidance will help take the load of explaining it here?)

[paulmsmith]

Followed along and seems to work nicely. 👍

Minor comments:

• Where we first mention Codespaces and Gitpod, perhaps we should link to information about them (landing pages)?
• The Codespaces billing is quite complicated, maybe we should give a simple explanation for it, e.g (assuming we're 2 cores?) you'll be limited to around 60 hours per month, so consider whether this is enough for your needs. - a bit tricky since that could change beyond our control…
• Same issue for Gitpod, which is I think, around 50 hours per month. (https://www.gitpod.io/docs/configure/billing)
• Step 1.1: repo link, we should call this NHS Prototype Kit repository rather than NHSUK, to align with other docs
• Step 1.4: a screenshot here could be helpful too, so that users can understand that what they're looking at is correct and that it's all 'done' and running, and ready for the next step (since it's quite a complex interface and takes time to run)
• Step 2: save changes, second para's second sentence missing a space "changes with GitHub.You can use"
• Should take a look at where this guide should be linked into from other bits of the docs, eg. link from 'install on an NHSE laptop' and the 'install guide', as an alternative method

Happy to make these changes myself if you prefer @paulmsmith

Need a review from @sarawilcox and then we'll be good to go.

If you can make those changes that would be great. I do struggle for time and probably will do until January now.

[vickytnz]

Hi @paulmsmith, I just had a go at this and I think it's good! I made a teeny tweak to capitalisation just to check how things work. I'll come back to this PR over the next few days to review the content fully. For now, I just wanted to get an idea how it works from a user's point of view.

It works very similarly to GitPod so I was familiar with this sort of set up but it will be completely new for some people, especially content designers.

I think Codespaces won't just be for people who can't install software. It's probably also good for people who don't have strong technical skills and are finding it difficult to install the prototype kit (or something like that).

I can see people creating a Codespace following this guide, but then getting stuck on the editing/working with Codespaces page. The page goes into saving changes, managing prototypes etc. But I suspect non-specialists will need more help getting started. Just knowing:

• what they should expect to see on their screen
• where to find the files they'll be working on (for most content designers, it'll be app/views)
• that you can change the HTML and it will update in the browser, so you can see your changes as you work

The page points people off to https://docs.github.com/en/codespaces/getting-started/quickstart. But I'm struggling to understand that page. It's quite technical and the examples are not the sort that content designers can relate to.

I think people will need more help saving their changes and committing back to GitHub. Don't know if it helps to take them through the few key commands that I use as a content designer:

• git status
• git add .
• git commit -m "...."
• git push
  And to suggest that they ask the dev or designer in their team for help if they're having problems.

I'll feedback more comments when I do a proper content review. I'm wondering if @LauraJD would like to have a go at this as someone completely new to using the kit in the browser.

I've been reviewing this in line with my guidance that I've just ported over, and I agree with Sara in that this may be a few separate things being pushed together:

1. installing the prototype on a web server using Codespaces
2. editing the prototype using Github and Codespaces.

I think that it may be safer to set up number 1 as more of a "for demo purposes" - mainly as if it's for proper work purposes it needs a lot more information that I allude to in my instructions (namely that people need to also get on the NHSD organisation and that isn't instant - I think particularly for this group the repo in the wrong place could be deeply confusing). The initial prototype kit instructions are very much 'on your computer only' and codespaces kinda forces the opposite and explaining git concepts early. the other fallback is doing a third version of 'what computer are you installing on and having 'mac / windows / web browser (for example Github Codespaces)' (as well as adding basic instructions to the advanced install guide)

For 2 - I think it's hard to go into it without giving an explanation of git and github - which makes me think if it justifies a relook at the github and github desktop instructions to either try and roll it up a a single set of github instructions, or find ways to figure out how they can all join up (or at the least where there is modular content that we can configure into blocks rather than managing duplicate content).

There may even be a missing 'editing github prototypes using web browser' that is a bridge to the 'run it with codespaces'. I also wonder if there's something about the balance of 'editing things on the browser is easier but means that you can't check what you are working on without it being online'

[anandamaryon1]

If you can make those changes that would be great. I do struggle for time and probably will do until January now.

@paulmsmith
Have pushed some changes to address most of the things I mentioned, and marked them in my original comment.

[frankieroberto]

I don’t think we need to include this file as this would just enable you to run the documentation website in Codespaces, rather than the kit itself, which is over here: https://github.com/nhsuk/nhsuk-prototype-kit/

But it might be useful to include anyway to allow us to try it out for making changes to the website?

[frankieroberto]

I wonder if we should avoid recommend using the 'fork' feature as that might cause some unexpected issues - eg if it defaults pull requests to being against the upstream repo instead of the forked one?

That said, the alternative right now would be to download the zip file and re-upload it which isn't ideal either.

Maybe it’s time to start looking at setting up a template repo sooner rather than later? 🤔

[anandamaryon1]

Hmm yes you're right, forking is not right, didn't realise how it maintains a connection to the main repo.

But following the normal way of downloading a zip to you computer then linking that up with a git repo then gets us back to doing stuff on your local machine…

Don't know about templates but sounds like it could be what we're looking for.

[frankieroberto]

I'll change it to reference the download and re-upload process for now, even if that’s a bit of a pain. It should still be helpful for people who can install Visual Studio or GitHub Desktop, but can't get Node.js running.

Will spin out a separate issue to investigate template repos.

[frankieroberto]

@paulmsmith @anandamaryon1 @vickytnz I've made a few tweaks (mainly to remove the suggesting of using the 'Fork' button for now).

I think we could put this live, and then get some feedback on it from a few people who try it out?

[vickytnz]

I think we need to manage expectations about using Codespaces for now as without a template it's actually pretty hard to do new? It might be possible to do it somehow with visual studio code but it's going to need instructions that I can't quite figure out right now.

[vickytnz]

@frankieroberto sorry i'm still figuring out how to show changes in the code editor - you'll need to go and look at my actual code change, oops.

Actually it is this:

---

1. Go to the prototype repository

Go to the GitHub repository for the prototype you wish to use. For this guide we will be using the NHS prototype kit repository.

If you do not have a prototype repository

Is it not possible right now to install the kit in a new Github repository unless you can install software on your computer.

You can try using Codespaces using the NHS prototype kit repository. You will not be able to save your progress.