Merge pull request #1313 from alphagov/update-guidance

Update main README and usage guidance

README.md

@@ -3,11 +3,12 @@ GOV.UK Publishing Components ·
 [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
 =====================
 
-This gem:
+GOV.UK Publishing Components is a Ruby gem to document and distribute components for GOV.UK applications.
 
-- Provides shared components for applications
-- Provides helpers to generate component payloads
-- Provides an application to preview components
+It provides:
+- a shared library of components
+- helpers to generate component payloads
+- an application to preview components and provide guidance
 
 Components should be added to this gem if they are required in more than one application, otherwise they should be added to that application.
 
@@ -19,7 +20,7 @@ Components should be added to this gem if they are required in more than one app
 - [Develop a component](/docs/develop-component.md)
 - [Run the component guide](/docs/run-component-guide.md)
 - [Move a component from an application to the gem](/docs/moving-components-upstream-into-this-gem.md)
-- [Publish this gem](/docs/publishing-to-rubygems.md)
+- [Publish/release a new version of the gem](/docs/publishing-to-rubygems.md)
 
 ## Architecture / structure
 
@@ -32,34 +33,28 @@ There are 2 types of helper classes in this app:
 - [AppHelpers](lib/govuk_publishing_components/app_helpers). Are exposed to the applications using this gem. They should be documented using RDoc.
 - [Component Presenters](lib/govuk_publishing_components/presenters). Anything in these classes is only for use within the components. They should be marked `@private`.
 
-## GOV.UK Frontend
+## Relationship with GOV.UK Design System
 
-This gem is the way GOV.UK consumes [GOV.UK Frontend](https://github.com/alphagov/govuk-frontend), part of the GOV.UK Design System.
+GOV.UK Publishing Components also makes [GOV.UK Design System](https://design-system.service.gov.uk/) styles and components available to GOV.UK's frontend applications. This gem consumes [GOV.UK Frontend](https://github.com/alphagov/govuk-frontend) via [NPM](https://www.npmjs.com/).
 
-We use NPM to pull in the GOV.UK Frontend styles and Javascript, but we don't commit
-the `node_modules` directory. To install GOV.UK Frontend on your machine, run:
-
-```
-npm install
-```
-
-You'll need to have installed Node and NPM for this.
+## Browser and assistive technology support
+GOV.UK Publishing Components shares the same standards in terms of browser and assistive technology support with [GOV.UK Frontend](https://github.com/alphagov/govuk-frontend#browser-and-assistive-technology-support).
 
 ## Documentation
 
 [See the rubydoc.info documentation](http://www.rubydoc.info/gems/govuk_publishing_components)
 
 Run the documentation locally with:
 
-```
+```sh
 bundle exec yard server --reload
 ```
 
 ## Running tests
 
 The default rake task runs all tests:
 
-```
+```sh
 bin/rake
 ```
 

docs/run-component-guide.md

@@ -1,24 +1,26 @@
-## Running the gem as a standalone app
+## Running the component guide as a standalone app
 
 If you want to work on this gem directly, without having to add it to another
-application, you can run it in the development vm or on your local machine with:
+application, you can run it on your local machine or using [govuk-docker](https://github.com/alphagov/govuk-docker). 
 
+To run it locally you'll need [Ruby](https://www.ruby-lang.org/en/downloads/) and [Node.js](https://nodejs.org/en/) installed to get this project running.
+
+### Running the component guide on your local machine
 ```
+cd ~/govuk/govuk_publishing_components
 ./startup.sh
 ```
 
-The app should start on http://localhost:3212 or http://publishing-components.dev.gov.uk/component-guide on GOV.UK development machines.
-
+The app should start on [http://localhost:3212/component-guide/](http://localhost:3212/component-guide/).
 
-#### Running with bowl on the VM
+### Running the component guide in [govuk-docker](https://github.com/alphagov/govuk-docker)
 
 ```
-$ cd /var/govuk/govuk_publishing_components
-$ bundle
-$ npm install
+cd ~/govuk/govuk-docker
+make govuk_publishing_components
 
-$ cd /var/govuk/govuk-puppet/development-vm
-$ bowl publishing-components
+cd ~/govuk/govuk_publishing_components
+govuk-docker-up
 ```
 
-Then visit [publishing-components.dev.gov.uk/component-guide](http://publishing-components.dev.gov.uk/component-guide).
+Then visit [http://govuk-publishing-components.dev.gov.uk/component-guide/](http://govuk-publishing-components.dev.gov.uk/component-guide/).