Merge pull request #804 from alphagov/update-package-readme

Update readme in npm package

CHANGELOG.md

@@ -53,6 +53,9 @@ Note: We're not following semantic versioning yet, we are going to talk about th
 - Add CHANGELOG_TEMPLATE to make changelogs easier for new contributors
   ([PR #798](https://github.com/alphagov/govuk-frontend/pull/798))
 
+- Update package `README`
+  ([PR #804](https://github.com/alphagov/govuk-frontend/pull/804))
+
 ## 0.0.32 (Breaking release)
 
 **This release changes the name of package.** It's now published as `govuk-frontend` on `npm`.

README.md

@@ -36,7 +36,7 @@ in your service.
 We recommend [installing GOV.UK Frontend using node package manager
 (npm)](docs/installation/installing-with-npm.md).
 
-### 2. Install by using built files
+### 2. Install by using compiled files
 
 You can also [download the compiled and minified assets (CSS, JavaScript) from
 GitHub](docs/installation/installing-from-dist.md).

docs/installation/installing-with-npm.md

@@ -6,7 +6,7 @@ To use GOV.UK Frontend with NPM you must:
 
 1. Install the long-term support (LTS) version of
    [Node.js](https://nodejs.org/en/), which includes NPM. The minimum version of
-   Node required is 8.6.0.
+   Node required is 4.2.0.
 
    (We recommend using [`nvm`](https://github.com/creationix/nvm) for managing
    versions of Node.)
@@ -110,8 +110,7 @@ $govuk-global-styles: true;
 
 Some of the JavaScript included in GOV.UK Frontend improves the usability and
 accessibility of the components. You should make sure that you are importing and
-initialising it in your application to ensure that all users can properly use it
-successfully.
+initialising Javascript in your application to ensure that all users can use it successfully.
 
 For example, the JavaScript will:
 
@@ -183,7 +182,7 @@ If you compile JavaScript in your project, your build tasks will already include
 something similar to the above task - in that case, you will just need to pipe
 `rollup` to it.
 
-### Import assets
+### Importing assets
 
 In order to import GOV.UK Frontend images and fonts to your project, you should configure your application to reference or copy the relevant GOV.UK Frontend assets.
 

package/README.md

@@ -1,60 +1,96 @@
-# GOV.UK Frontend - All components
+# GOV.UK Frontend
 
-All of the components in GOV.UK Frontend, in a single package.
+GOV.UK Frontend contains the code you need to start building a user interface
+for government platforms and services.
 
-## Guidance
+See live examples of GOV.UK Frontend components, and guidance on when to use
+them in your service, in the [GOV.UK Design System](https://www.gov.uk/design-system).
 
-Find out when to use the Back link component in your service in the [GOV.UK Design System](https://govuk-design-system-production.cloudapps.digital).
+## Contact the team
 
-## Dependencies
+GOV.UK Frontend is maintained by a team at Government Digital Service. If you want to know more about GOV.UK Frontend, please email the [Design System
+team](mailto:govuk-design-system-support@digital.cabinet-office.gov.uk) or get in touch with them on [Slack](https://ukgovernmentdigital.slack.com/messages/govuk-design-system).
 
-To consume all components you must be running npm version 5 or above.
+## Quick start
 
-## Installation
+There are 2 ways to start using GOV.UK Frontend in your app.
 
-    npm install --save govuk-frontend
+Once installed, you will be able to use the code from the examples in the
+[GOV.UK Design System](https://www.gov.uk/design-system in your service.
 
-## Requirements
+### 1. Install with npm (recommended)
 
-### Build tool configuration
+We recommend [installing GOV.UK Frontend using node package manager
+(npm)](https://github.com/alphagov/govuk-frontend/blob/master/docs/installation/installing-with-npm.md).
 
-When compiling the Sass files you'll need to define includePaths to reference the node_modules directory. Below is a sample configuration using gulp
+### 2. Install by using compiled files
 
-    .pipe(sass({
-      includePaths: 'node_modules/'
-    }))
+You can also [download the compiled and minified assets (CSS, JavaScript) from
+GitHub](https://github.com/alphagov/govuk-frontend/blob/master/docs/installation/installing-from-dist.md).
 
-### Static asset path configuration
+## Importing styles
 
-To show the button image you need to configure your app to show these assets. Below is a sample configuration using Express js:
+You need to import the GOV.UK Frontend styles into the main Sass file in your
+project. You should place the below code before your own Sass rules (or Sass
+imports) if you want to override GOV.UK Frontend with your own styles.
 
-    app.use('/assets', express.static(path.join(__dirname, '/node_modules/govuk-frontend/assets')))
+To import add the below to your Sass file:
 
-### Setting up Nunjucks views and paths
+  ```scss
+  @import "node_modules/govuk-frontend/all";
+  ```
 
-Below is an example setup using express configure views:
+[More details on importing styles](https://github.com/alphagov/govuk-frontend/blob/master/docs/installation/installing-with-npm.md#importing-styles)
 
-    nunjucks.configure('node_modules/govuk-frontend/components/', {
-      autoescape: true,
-      cache: false,
-      express: app
-    })
+## Importing JavaScript
+
+Some of the JavaScript included in GOV.UK Frontend improves the usability and
+accessibility of the components. You should make sure that you are importing and
+initialising Javascript in your application to ensure that all users can use it successfully.
+
+You can include Javascript for all components either by copying the `all.js` from `node_modules/govuk-frontend` into your application or referencing the file directly:
+
+```html
+<script src="<path-to-govuk-frontend-all-file>/all.js"></script>
+```
+Next you need to initialise the script by adding:
+
+```html
+<script>window.GOVUKFrontend.initAll()</script>
+```
+
+[More details on importing Javascript and advanced options](https://github.com/alphagov/govuk-frontend/blob/master/docs/installation/installing-with-npm.md#importing-javascript)
 
-## Getting updates
 
-To check whether you have the latest version of the button run:
+## Importing assets
+
+In order to import GOV.UK Frontend images and fonts to your project, you should configure your application to reference or copy the relevant GOV.UK Frontend assets.
+
+[More details on importing assets](https://github.com/alphagov/govuk-frontend/blob/master/docs/installation/installing-with-npm.md#import-assets)
+
+
+## Getting updates
 
-    npm outdated govuk-frontend
+To check whether you have the latest version of GOV.UK Frontend, run:
 
-To update the latest version run:
+```
+npm outdated govuk-frontend
+```
 
-    npm update govuk-frontend
+To update to the latest version, run:
 
+```
+npm update govuk-frontend
+```
 
-## Contribution
+## Licence
 
-Guidelines can be found at [on our Github repository.](https://github.com/alphagov/govuk-frontend/blob/master/CONTRIBUTING.md "link to contributing guidelines on our github repository")
+Unless stated otherwise, the codebase is released under the MIT License. This
+covers both the codebase and any sample code in the documentation. The
+documentation is &copy; Crown copyright and available under the terms of the
+Open Government 3.0 licence.
 
-## License
+## Contribution guidelines
 
-MIT
+If you want to help us build GOV.UK Frontend, view our [contribution
+guidelines](https://github.com/alphagov/govuk-frontend/blob/master/CONTRIBUTING.md).