Merge pull request #579 from alphagov/readme

Update README to follow guidance
alphagov · Apr 16, 2015 · d3a30d0 · d3a30d0
2 parents c1a6138 + 8707954
commit d3a30d0
Show file tree

Hide file tree

Showing 5 changed files with 102 additions and 78 deletions.
diff --git a/README.md b/README.md
@@ -1,20 +1,31 @@
-GOV.UK shared static assets
-===========================
+# Static
 
-This repository contains global stylesheets and templates for [GOV.UK](https://www.gov.uk).
+This application defines global templates for [GOV.UK](https://www.gov.uk) pages.
 
-Other related repositories:
+## Screenshots
 
-* [alphagov/govuk_frontend_toolkit](https://github.com/alphagov/govuk_frontend_toolkit) - an SCSS toolkit for building responsive and cross-browser friendly web sites
-* [alphagov/slimmer](https://github.com/alphagov/slimmer) - Rack middleware for wrapping Rack applications in shared templated layouts
+![screenshot](/doc/screenshot.png?raw=true)
 
-## Javascript unit tests
 
-Tests can run in browser at `/specs`
+## Nomenclature
+
+* [slimmer](https://github.com/alphagov/slimmer) - Rack middleware for wrapping Rack applications in shared templated layouts
+
+## Technical documentation
+
+There are docs for:
 
-Or in terminal by running `bundle exec rake`, `bundle exec rake test` or to run only the jasmine tests you can use `bundle exec rake spec:javascript`
+- [Image optimisation](docs/image-optimisation.md)
+- [GOV.UK components](docs/govuk-components.md)
+- [Slimmer templates](doc/slimmer_templates.md)
 
-##Running Locally
+### Running the application
+
+`./startup.sh`
+
+This will start the server running on http://0.0.0.0:3013
+
+#### Running Locally
 
 If you'd like to run static locally, and keep all its asset links pointing to
 the same local instance, you'll need to set `PLEK_SERVICE_STATIC_URI`, which is
@@ -29,76 +40,15 @@ To run this app locally, and have it point at its own assets, run it like this:
 PLEK_SERVICE_STATIC_URI=0.0.0.0:3013 ./startup.sh
 ```
 
-## GOV.UK components
-
-Shared partials that encapsulate the HTML/CSS/JS for a common UI component.
-The component files are centrally hosted on static and exposed to applications via [alphagov/slimmer](https://github.com/alphagov/slimmer).
-The partial is exposed over the network, and the CSS/JS are included by the shared templated layout.
-
-The available components and their documentation are exposed by an API at `/templates/govuk_component/docs`, which is consumed by
-[alphagov/govuk_component_guide](https://github.com/alphagov/govuk_component_guide) to generate a living styleguide for components.
-
-* a [Partial View](app/views/govuk_component) - The template logic and markup, also defines the arguments expected
-* a [SCSS module](app/assets/stylesheets/govuk-component) - The styling of the component
-* a Javascript module - no examples yet.
-* Documentation - currently in a [static/central file](app/views/govuk_component/docs.json), this will generated dynamically in the future
-
-### Creating a new component
-
-There's a rails generator you can use to create the basic component files, but it's recommended you read below to understand how it works as well.
-
-```
-bundle exec rails generate govuk_component [your-component-name]
-```
-
-### How components are structured
+### Running the test suite
 
-Component names should be lowercase and hyphenated. For example: `your-component-name`.
+`bundle exec rake` runs the test suite.
 
-When referenced from an application as a partial they'll be prefixed with `govuk-`. For example: `govuk-your-component-name`.
+#### Javascript unit tests
 
-To match rails view convention the partial itself should use an underscore, rather than a hyphen.
-
-1) views live in `app/views/govuk_component/your_compontent_name.raw.html.erb` - There should be a single root element, with a class name consisting of the prefixed component name. For example:
-```
-<div class="govuk-your-component-name">
-<p>things</p>
-</div>
-```
-
-2) There is a SCSS module at `app/stylesheets/govuk-component/_your-component-name.scss` - there should be a single root class, the same class on the root of the partial. For example:
-```
-.govuk-your-component-name {
-  // CSS rules go here.
-  p {
-    // scoped rules
-  }
-}
-```
-
-3) SCSS modules are included in `app/stylesheets/govuk-component/_component.scss` - which is used in the standard static layout SCSS files (application.scss, header_footer_only.scss)
-
-4) Documentation lives `app/views/govuk_component/docs.json` - this is in the form of an array of hashes:
-* `id`: The underscore version of the component name
-* `name`: The human name. eg, `Your Example Component`
-* `description`: A longer form description of what the component does, when it should be used
-* `fixtures`: TBD: For components that expect arguments this will be a hash of fixtured example arguments
-
-Adding it to the documentation will allow you to preview it in the `govuk_component_guide`, which can be pointed to any
-version of static, including your local one running a branch. Which you should probably do.
-
-## Image Optimisation
-
-### Why?
-
-PNGs, GIFs and some other image formats can be optimised to make the images smaller without losing any quality.  Smaller image files can be downloaded quicker by web browsers, and this can significantly improve user experience.
+Tests can run in browser at `/specs`
 
-### How?
+Or in terminal to run only the jasmine tests you can use `bundle exec rake spec:javascript`
 
-Images should be compressed before committing them to git.  This can be done via:
 
-```
-bundle exec image_optim --no-pngcrush --no-svgo -r app/
-```
 
-This may require some extra binaries to be installed on your system - please read the output of the above command or see https://github.com/toy/image_optim for more details.
diff --git a/doc/README_FOR_APP b/doc/README_FOR_APP
diff --git a/doc/govuk-components.md b/doc/govuk-components.md
@@ -0,0 +1,57 @@
+# GOV.UK components
+
+Shared partials that encapsulate the HTML/CSS/JS for a common UI component.
+The component files are centrally hosted on static and exposed to applications via [alphagov/slimmer](https://github.com/alphagov/slimmer).
+The partial is exposed over the network, and the CSS/JS are included by the shared templated layout.
+
+The available components and their documentation are exposed by an API at `/templates/govuk_component/docs`, which is consumed by
+[alphagov/govuk_component_guide](https://github.com/alphagov/govuk_component_guide) to generate a living styleguide for components.
+
+* a [Partial View](app/views/govuk_component) - The template logic and markup, also defines the arguments expected
+* a [SCSS module](app/assets/stylesheets/govuk-component) - The styling of the component
+* a Javascript module - no examples yet.
+* Documentation - currently in a [static/central file](app/views/govuk_component/docs.json), this will generated dynamically in the future
+
+## Creating a new component
+
+There's a rails generator you can use to create the basic component files, but it's recommended you read below to understand how it works as well.
+
+```
+bundle exec rails generate govuk_component [your-component-name]
+```
+
+## How components are structured
+
+Component names should be lowercase and hyphenated. For example: `your-component-name`.
+
+When referenced from an application as a partial they'll be prefixed with `govuk-`. For example: `govuk-your-component-name`.
+
+To match rails view convention the partial itself should use an underscore, rather than a hyphen.
+
+1) views live in `app/views/govuk_component/your_compontent_name.raw.html.erb` - There should be a single root element, with a class name consisting of the prefixed component name. For example:
+```
+<div class="govuk-your-component-name">
+<p>things</p>
+</div>
+```
+
+2) There is a SCSS module at `app/stylesheets/govuk-component/_your-component-name.scss` - there should be a single root class, the same class on the root of the partial. For example:
+```
+.govuk-your-component-name {
+  // CSS rules go here.
+  p {
+    // scoped rules
+  }
+}
+```
+
+3) SCSS modules are included in `app/stylesheets/govuk-component/_component.scss` - which is used in the standard static layout SCSS files (application.scss, header_footer_only.scss)
+
+4) Documentation lives `app/views/govuk_component/docs.json` - this is in the form of an array of hashes:
+* `id`: The underscore version of the component name
+* `name`: The human name. eg, `Your Example Component`
+* `description`: A longer form description of what the component does, when it should be used
+* `fixtures`: TBD: For components that expect arguments this will be a hash of fixtured example arguments
+
+Adding it to the documentation will allow you to preview it in the `govuk_component_guide`, which can be pointed to any
+version of static, including your local one running a branch. Which you should probably do.
diff --git a/doc/image-optimisation.md b/doc/image-optimisation.md
@@ -0,0 +1,19 @@
+# Image optimisation
+
+## Why?
+
+PNGs, GIFs and some other image formats can be optimised to make the images
+smaller without losing any quality.  Smaller image files can be downloaded
+quicker by web browsers, and this can significantly improve user experience.
+
+## How?
+
+Images should be compressed before committing them to git.  This can be done via:
+
+```
+bundle exec image_optim --no-pngcrush --no-svgo -r app/
+```
+
+This may require some extra binaries to be installed on your system - please
+read the output of the above command or see https://github.com/toy/image_optim
+for more details.
diff --git a/doc/screenshot.png b/doc/screenshot.png