alphagov / prototype-kit-training

Documentation for GOV.UK Prototype Kit training

GOV.UK Prototype Kit training has moved

All content in this app has now been moved to the GOV.UK Prototype Kit website, https://govuk-prototype-kit.herokuapp.com/docs/tutorials-and-examples.

A redirect from the prototype kit training website has been set up, see govuk-prototype-kit#1275 for more details.

This repo has now been archived, if you wish to raise an issue please do so on the Prototype Kit repo.

prototype-kit-training

This documentation contains tutorials that are intended to take an absolute beginner through the basics of the GOV.UK Prototype Kit.

It uses the Tech Docs Template, and can be set up locally and run by following the instructions in the repo's readme.

prototype-kit-training's Issues

Update content on GitHub to account for 2FA

In the current content on pushing to GitHub for the first time, we don't mention what to do if an account is secured with 2FA.

https://prototype-kit-training.cloudapps.digital/task-5.html#push-the-staged-commits-to-the-remote-repo

During the training some users struggled to push their local commits to the remote repo because they needed to generate a personal access token.

This is only applicable to first commits in the terminal and isn't a concern where users commit via GitHub for Desktop.

To ensure users of the kit can follow the guidance in the training material and upload their prototype to GitHub via the terminal, additional instructions are needed.

https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line

Sort out Prototype Kit Training docs deployment

This repo is currently deployed to the gds-design / prototypes space on PaaS using GitHub actions:

prototype-kit-training/.github/workflows/main.yml

Line 37 in 554bb7a

cf target -o gds-design -s prototypes

It's deployed using credentials associated with @DebsDee .

We need to move away from GitHub Actions, and use credentials that are not tied to any individual.

Done when

• The site (https://prototype-kit-training.cloudapps.digital/) is deployed using Travis whenever the master branch changes
• The site is deployed into the govuk-design-system/production space
• Credentials used to deploy the site are in our shared credential store

Update review date on Prototype Kit Accessibility Statement

What?

Update date of review, under 'Preparation of this accessibility statement,' on the PK Accessibility Statement.

Why?

Tech writing leads have decided that we should update the part of the statements that says when the statements were last updated (very meta!).

Who needs to know about this

@EoinShaughnessy, @joelanman

Done when

• Eoin has drafted update
• Joe has reviewed and approved

Rename the default branch to `main`

The default branch for this repository will soon be renamed from master - a potentially offensive term - to main. Many other GitHub communities are also renaming their default branches. To learn more about this welcome news, check out Git’s statement about why branch renaming matters.

You may need to make changes if you have a local copy or fork of this repository. You can view our guidance on this Github issue.

Introduction section has empty expandable area

What did you do? (steps to reproduce)

Went to the homepage

What happened? (actual results)

saw that 'introduction' has an expandable area but no items

What should have happened? (expected results)

saw that 'introduction' has an expandable area should have items for the headings, or no expandable area.

Participants don't realise they only need to set up the git remote once.

This issue was observed whilst facilitating Prototype Kit training in Manchester on 20 February 2020.

At least one participant did not realise that they only needed to set up the GitHub remote once, and that when they wanted to push changes in the future they could jump straight to git push -u origin master.

Because they had already had a remote with that name, they were getting an error message that they did not understand when they were trying to set up the remote again.

prototype-kit-training/source/task5/task5.md

Lines 69 to 83 in 5db3119

	1. Go to the remote repo in GitHub. This is the empty repo created earlier.
	1. Select the __Clone or download__ button.
	1. Select __Use HTTPS__ .
	1. Select the copy button.
	1. Back in the command line, link the local repo to the remote repo by typing:
	```
	git remote add origin REMOTE-REPO-URL
	```
	Where `REMOTE-REPO-URL` is the copied URL.

Broken link

What did you do? (steps to reproduce)

https://prototype-kit-training.cloudapps.digital/task-2.html#task-2-adding-questions-to-your-pages

Followed link - "Follow the tutorial on how to add questions to your question pages."

What happened? (actual results)

Destination page not found - https://govuk-prototype-kit.herokuapp.com/docs/make-first-prototype/add-questions

What should have happened? (expected results)

Page found and content loaded

Add accessibility statement

We need to add an accessibility statement by 23 September 2020 (based on the GOV.UK accessibility statement template), showing how/whether this documentation meets WCAG 2.1.

Remove references to accessibility issues in Frontend Docs from accessibility statement [before 31 March]

What

Once #52 has been merged and deployed, update the accessibility statement to remove the reference to issues caused by the technical documentation template, and update the compliance status.

Why

The known accessibility issues should be resolved by updating to v2.2.0 of the template. (The prototype kit training docs do not have any tables, so there's nothing to do re row headers)

Done when

• References to issues in Frontend Docs removed
• Compliance status updated
• Changes 2i'ed

Participants aren't clear how to link from their prototype from the index page

This issue was observed whilst facilitating Prototype Kit training in Manchester on 20 February 2020.

We saw a number of participants who were unclear how to do this, as they weren't sure where the link should go.

We might want to be more instructional about exactly where / how to add the link.

We could also consider making it a stretch task in a later step, when they may be more confident reading and changing HTML.

prototype-kit-training/source/task1/task1.md

Lines 18 to 22 in 5db3119

	### Link to your prototype from the index page
	If you go to `localhost:3000` you can see the default index page for the prototype kit.
	Change the page so that it clearly links to your Juggling service start page.

Participants get lost in Prototype Kit documentation

This issue was observed whilst facilitating Prototype Kit training in Manchester on 20 February 2020.

Once participants clicked through from a task to the Prototype Kit documentation, they seemed to stay in the Prototype Kit documentation unless they were directed back to the training docs.

This seemed to be particularly problematic after task 3, as they ended up following the link from https://govuk-prototype-kit.herokuapp.com/docs/make-first-prototype/link-index-page-start-page to https://govuk-prototype-kit.herokuapp.com/docs/creating-routes which was a lot harder to follow than the training documentation on routing.

Participants don't know how to pass data to macros in task 3's stretch task

This issue was observed whilst facilitating Prototype Kit training in Manchester on 20 February 2020.

The task 3 stretch task (using Nunjucks macros) does not tell the user how to pass the answer the answer gave to the macro (i.e. the use of value: data['foo'])

We had lots of participants asking how to do this when we reached this step.

prototype-kit-training/source/task3/task3.md

Lines 12 to 18 in 5db3119

	### Use some nunjucks macros in your prototype
	In task 2 you added some questions to your pages. To do that you copied and pasted HTML code from the [GOV.UK Design System](https://design-system.service.gov.uk/).
	Now we've talked a bit about Nunjucks macros, try replacing some HTML elements with the equivalent Nunjucks code.
	A good place to start would be the radio buttons on your `juggling-balls.html` page.

Fix accessibility issues in Prototype Kit Training docs

What

Audit and fix accessibility issues in GOV.UK Prototype Kit Training docs, and publish accessibility statement content.

Why

This is part of an overall accessibility audit of our Tech Docs Template technical documentation across GDS. It's being led by Mark and Jon Glassman.

We want to publish accessibility statements (or accessibility notes in wider product accessibility statements) for Tech Docs Template technical documentation by September.

Who needs to know

Tim, Chris, Rosie

Done when

• We've audited Prototype Kit Training docs for accessibility issues
• We've identified which issues to fix
• We've fixed the issues

Prepare for transition to the Prototype Kit site

We are moving all missing content to the Prototype Kit site

When that is done, we'll need to turn this site off and redirect all the pages.

Tasks

• investigate where and how the training site is hosted and deployed
• create redirects
• deploy redirects to replace the training site

Participants who intialise their new GitHub repo with a README get stuck when they come to push

This issue was observed whilst facilitating Prototype Kit training in Manchester on 20 February 2020.

When creating the repo on GitHub, one of the users chose to intialise the repository with a README.

This caused them issues when they came to push, as they had two different histories that could not be reconciled. This can be hard to resolve – we ended up deleting the repository on GitHub and recreating it.

Fix continuous deployment

What

Fix continuous deployment of the prototype kit training docs, which is currently broken.

Why

The deploy stage is failing on the master branch, which means changes are no longer being deployed automatically.

Starting deployment for app prototype-kit-training in org govuk-design-system / space prototype-kit-training as [email protected]...
OK
Waiting for app to start...
Start app timeout
TIP: Application must be listening on the right port. Instead of hard coding the port, use the $PORT environment variable.
Use 'cf logs prototype-kit-training --recent' for more information

FAILED
Script failed with status 1
failed to deploy

We think this is because we're still using the v3 prefixed commands to deploy:

prototype-kit-training/bin/deploy-travis

Lines 11 to 14 in 8b26e0d

	cf v3-create-app $APP_NAME
	cf v3-apply-manifest -f manifest.yml
	# Deploy using CloudFoundry zero-downtime push
	cf v3-zdt-push $APP_NAME -p build --wait-for-deploy-complete

And, roughly:

• v3- commands were experimental, while they worked on the API
• v7 CLI came out, and uses the v3 API in a not-experimental way (i.e. it’s supported properly)
• The v3- commands weren’t updated to work with newer versions of the API

So we think the solution is to upgrade to the V7 version of the CLI, and use non-prefixed commands.

Further details

The same issue came up in the learn-to-code repo, and was fixed by the changes in alphagov/learn-to-code#40.

We also had this problem in frontend docs – see alphagov/govuk-frontend-docs#91.