expand the more minimal sections and add an overview

1 files changed, 42 insertions, 13 deletions

diff --git a/notes/customisation.pod b/notes/customisation.pod
index 7812f23bc..ffde273cf 100644
--- a/notes/customisation.pod
+++ b/notes/customisation.pod
@@ -10,27 +10,52 @@ area it accepts queries for and translating the text.
 
 It also includes information about how to change the design.
 
-=head1 TEMPLATES
+=head1 OVERVIEW
+
+FixMyStreet implements a Cobrand system in order to allow customisation
+of the default behavior. The cobrand is made up of a set of templates for
+the cobrand and a Cobrand module that contains code that customises the
+way the cobrand behaves. There are defaults for both of these so the
+Cobrand only needs to override things that are specific to it.
+
+Customisations should be implemented like this as this means that any
+upgrade to FixMyStreet will not overwrite your changes.
+
+The custom when creating a Cobrand is to name it after your site, e.g.
+if your site was called FixMyPark then you would call the Cobrand
+FixMyPark.
 
-FixMyStreet uses a cobrand system to implement customisation. There
-are two parts to a cobrand: the templates and the cobrand module.
+The default cobrand is called Default.
+
+=head1 TEMPLATES
 
 Templates are found in the templates directory. Within that there are
 seperate directories for web templates and email templates. Under each
-of these there is a directory for each cobrand.
+of these there is a directory for each cobrand. In our FixMyPark example
+this would be L<templates/web/fixmypark> for the web templates and
+L<templates/email/fixmypark> for the email templates.
 
 The full set of templates is stored in the default cobrand and if no
 equivalent template is found in a cobrand directory FixMyStreet will
 use the default template.
 
-At a bare minimum you will probably want to change the header and footer
-templates.
+At a bare minimum you will probably want to copy the header and footer
+web templates found in L<templates/web/default/header.html> and
+L<templates/web/default/footer.html> into your cobrand and make appropriate
+changes.
+
+The other template you should make your own version of is the FAQ which
+is in L<templates/web/default/faq-en-gb.html>
 
 =head1 CSS
 
 The CSS is stored in web/css/ under which there are directories for cobrands
 but this is only by custom. The loading of the css is controled by the header
-templates.
+templates. Note that FixMyStreet uses sccs files to generate our CSS so by there
+are no CSS files until L<bin/make_css> has been run.
+
+The CSS provided with FixMyStreet uses CSS3 media queries in order to adapt
+the layout to work on different devices.
 
 The CSS is structured into two main files:
 
@@ -130,23 +155,27 @@ the address in reports and rss feeds or alerts.
 
 =item allow_photo_upload
 
-Return 0 to disallow photo upload.
+Return 0 to disable the photo upload field.
 
 =item allow_photo_display
 
-Return 0 to disallow photo display.
+Return 0 to disable the display of uploaded photos.
 
 =item area_types
 
-This returns a list of MaPit area type codes that the site handles.
+If you are using MaPit alongside FixMyStreet this should return a
+list of the area type codes that the site will handle. This is used
+to filter the data returned from MaPit so that only appropriate areas are
+displayed.
 
 =item remove_redundant_councils
 
 This is used to filter out any overlapping jurisdictions from MaPit results
 where only one of the authorities actually has reponsability for the events
-reported by the site. And example woulbe be a report in a city where MaPit
-has an id for the city council and the state council but we only ever report
-problems to the state.
+reported by the site. An example would be be a report in a city where MaPit
+has an id for the city council and the state council but problems are only
+reported to the state. In this case you would remove the id for the the city
+council from the results.
 
 =item short_name