Update documentation

README.md

@@ -28,40 +28,63 @@ Read more in [Lisa Scott's GDS blog post](https://gds.blog.gov.uk/2012/02/16/sma
 
 ## Technical documentation
 
-This is a Ruby on Rails application that both contains and serves the Smart Answers stored in this repository. Smart Answers are presented to public users.
+This is a Ruby on Rails application that contains:
 
-**NOTE.** This application doesn't use a database.
+* A Rails application to serve Smart Answers
+* A DSL for creating Smart Answers
+* The Smart Answers that appear on GOV.UK
 
-Read more about the [structure and syntax of Smart Answers](doc/smart-answers-flows.md).
+**NOTE.** This application doesn't use a database and as such it [does not include the ActiveRecord Railtie in application.rb](https://github.com/alphagov/smart-answers/blob/4eb1b80a698e6835e745c4ad1954a3892e929b64/config/application.rb#L3).
 
 ### Dependencies
 
 * [alphagov/static](https://github.com/alphagov/static): provides static assets (JS/CSS) and the GOV.UK templates.
 
 ### Running the application
 
-See [development using the GDS development virtual machine](developing-using-vm.md).
+See:
+
+* [Developing with the GDS development VM](doc/developing-using-vm.md)
+* [Developing without the GDS development VM](doc/developing-without-vm.md)
 
 ### Running the test suite
 
     $ bundle exec rake
 
-### Process
+### Smart Answers
 
-* [Archiving a Smart Answer](doc/archiving.md)
-* [Continuous integration](doc/continuous-integration.md)
+* [File structure](doc/file-structure.md)
+* [Flow definition](doc/flow-definition.md)
+* [Question types](doc/question-types.md)
+* [Next node rules](doc/next-node-rules.md)
+* [Storing data](doc/storing-data.md)
+* [ERB templates](doc/erb-templates.md)
+  * [Landing page template](doc/landing-page-template.md)
+  * [Question templates](doc/question-templates.md)
+  * [Outcome templates](doc/outcome-templates.md)
+
+### Smart Answer flow development
+
+* [Development principles](doc/development-principles.md)
 * [Deploying changes for Factcheck](doc/factcheck.md)
-* [Deploying](doc/deploying.md)
 * [Merging pull requests from the content team](doc/merging-content-prs.md)
+* [Refactoring existing Smart Answers](doc/refactoring.md)
+* Adding [content-ids](doc/content-ids.md) to Smart Answers
+* [Creating a new Smart Answer](doc/creating-a-new-smart-answer.md)
+* [Archiving a Smart Answer](doc/archiving.md)
+* [Updating worldwide fixture data](doc/updating-worldwide-fixture-data.md)
 
-### Development
+### Smart Answers app development
 
-* Adding [content-ids](doc/content-ids.md) to Smart Answers.
-* [Developing using the VM](doc/developing-using-vm.md)
-* [Issues and Todo](https://github.com/alphagov/smart-answers/issues)
+* [Common errors you might run into during development](doc/common-errors.md)
+* [Environments](doc/environments.md)
+* [Continuous integration](doc/continuous-integration.md)
+* [Describing pull requests](doc/pull-requests.md)
+* [Deploying](doc/deploying.md)
+* [Handling exceptions with Errbit](doc/errbit.md)
 * [Rubocop](doc/rubocop.md)
 * [Testing](doc/testing.md)
-* [Updating worldwide fixture data](doc/updating-worldwide-fixture-data.md)
+* [Issues and Todo](https://trello.com/b/7HgyU4hy/smart-answers-tasks)
 
 ### Debugging
 

doc/adding-new-regression-tests.md

@@ -1,19 +1,23 @@
 # Adding new regression tests
 
-1. Update the flow to replace any single line conditionals around `Phraselist`s with multiple line conditionals. This is so that we get useful information from the running the coverage utility. Single line conditionals will show up as having been exercised irrespective of whether they caused something to be added to the `Phraselist`.
+1. Update the flow to replace any single line conditionals with multiple line conditionals. This is so that we get useful information from running the coverage utility. Single line conditionals will show up as having been exercised irrespective of whether the code they were guarding was exercised.
 
-        # Replace single line conditional
-        phrases << :new_phrase if condition
+```ruby
+# Replace single line conditional
+array << :value if condition
 
-        # With multiple line alternative
-        if condition
-          phrases << :new_phrase
-        end
+# With multiple line alternative
+if condition
+  array << :value
+end
+```
 
 2. Generate a set of responses for the flow that you want to add regression tests to.
 
-        $ rails r script/generate-questions-and-responses-for-smart-answer.rb \
-          <name-of-smart-answer>
+```bash
+$ rails r script/generate-questions-and-responses-for-smart-answer.rb \
+  <name-of-smart-answer>
+```
 
 3. Commit the generated questions-and-responses.yml file (in test/data) to git.
 
@@ -29,18 +33,20 @@
 
 6. Generate a set of input responses and expected results for the Smart Answer.
 
-        $ rm -rf coverage && \
-          TEST_COVERAGE=true \
-          rails r script/generate-responses-and-expected-results-for-smart-answer.rb \
-          <name-of-smart-answer>
+```bash
+$ rm -rf coverage && \
+  TEST_COVERAGE=true \
+  rails r script/generate-responses-and-expected-results-for-smart-answer.rb \
+  <name-of-smart-answer>
+```
 
 7. Inspect the code coverage report for the Smart Answer under test (`open coverage/rcov/index.html` and find the smart answer under test).
 
   * If all the branches in the flow have been exercised then you don't need to do anything else at this time.
 
       * Code in node-level blocks (e.g. in `value_question`, `date_question`, `multiple_choice` & `outcome` blocks) will always be executed at *flow-definition-time*, and so coverage of these lines is of **no** significance when assessing test coverage of the flow logic.
 
-      * Code in blocks inside node-level blocks (e.g. in `precalculate`, `next_node_calculation`, `validate` & `define_predicate` blocks) will be executed at *flow-execution-time*, and so coverage of these lines is of significance when assessing test coverage of the flow logic.
+      * Code in blocks inside node-level blocks (e.g. in `precalculate`, `next_node_calculation` & `validate` blocks) will be executed at *flow-execution-time*, and so coverage of these lines is of significance when assessing test coverage of the flow logic.
 
       * Coverage of code in ancillary classes (e.g. calculators) should also be considered at this point.
 
@@ -54,16 +60,20 @@
 
 9. Generate a yaml file containing the set of source files that this Smart Answer depends upon. The script will automatically take the ruby flow file, locale file and erb templates into account. You just need to supply it with the location of any additional files required by the Smart Answer (e.g. calculators and data files). This data is used to determine whether to run the regression tests based on whether the source files have changed.
 
-        $ rails r script/generate-checksums-for-smart-answer.rb \
-          <name-of-smart-answer> \
-          <path/to/additional/files>
+```bash
+$ rails r script/generate-checksums-for-smart-answer.rb \
+  <name-of-smart-answer> \
+  <path/to/additional/files>
+```
 
 10. Commit the generated yaml file to git.
 
 11. Run the regression test to generate the Govspeak of each landing page and outcome reached by the set of input responses.
 
-        $ RUN_REGRESSION_TESTS=<name-of-smart-answer> \
-          ruby test/regression/smart_answers_regression_test.rb
+```bash
+$ RUN_REGRESSION_TESTS=<name-of-smart-answer> \
+  ruby test/regression/smart_answers_regression_test.rb
+```
 
 If you want individual tests to fail early when differences are detected, set `ASSERT_EACH_ARTEFACT=true`.
 Note that this more than doubles the time it takes to run regression tests.

doc/common-errors.md

@@ -0,0 +1,63 @@
+# Errors
+
+A list of some of the errors you might run into when developing on Smart Answers locally.
+
+
+## "NoMethodError" when visiting the root URL
+
+You'll see this error if you visit the root URL of the Smart Answers app (e.g. http://localhost:3000 or http://smartanswers.dev.gov.uk/). This is because we don't have anything configured to respond at this path.
+
+### Exception
+
+```
+NoMethodError at /
+undefined method `to_html' for nil:NilClass
+```
+
+### Resolution
+
+Visit a specific Smart Answer, e.g. /marriage-abroad.
+
+
+## "SocketError" when viewing a Smart Answer
+
+__NOTE.__ This is specifically when the exception is raised in `SmartAnswerPresenter#artefact`.
+
+You'll see this error if the Smart Answers app can't connect to the Content API.
+
+### Exception
+
+```
+SocketError at /marriage-abroad
+getaddrinfo: nodename nor servname provided, or not known
+```
+
+### Resolution
+
+There are a couple of solutions to this problem:
+
+1. Set the `PLEK_SERVICE_CONTENTAPI_URI` environment variable to a valid host. NOTE. This doesn't need to be hosting the Content API (although you can use "https://www.gov.uk/api" if that's what you want), it simply needs to be a host that responds to HTTP requests.
+
+2. Configure a web server (e.g. Apache) on your machine to respond to http://contentapi.dev.gov.uk. This is the default location of the Content API in development so configuring this means that you won't have to set the `PLEK_SERVICE_CONTENTAPI_URI` environment variable.
+
+
+## "Slimmer::CouldNotRetrieveTemplate" when viewing a Smart Answer
+
+You'll see this error if the Smart Answers app can't connect to the [Static][static] host.
+
+### Exception
+
+```
+Slimmer::CouldNotRetrieveTemplate at /marriage-abroad
+Unable to fetch: 'wrapper' from 'http://static.dev.gov.uk/templates/wrapper.html.erb' because getaddrinfo: nodename nor servname provided, or not known
+```
+
+### Resolution
+
+There are a couple of solutions to this problem:
+
+1. Set the `PLEK_SERVICE_STATIC_URI` environment variable to "https://assets-origin.preview.alphagov.co.uk", which is the static/assets server running in preview.
+
+2. Run the static/assets server locally at http://static.dev.gov.uk. This is the default location of the static/asset server in development so configuring this  means that you won't have to set the `PLEK_SERVICE_STATIC_URI` environment variable.
+
+[static]: https://github.com/alphagov/static

doc/content-ids.md

@@ -2,4 +2,6 @@
 
 Smart answers need content-ids. You can generate one by running:
 
-    $ be rails r "puts SecureRandom.uuid"
+```bash
+$ be rails r "puts SecureRandom.uuid"
+```

doc/creating-a-new-smart-answer.md

@@ -0,0 +1,78 @@
+# Creating a new Smart Answer
+
+This walks through the basics of creating a new Smart Answer.
+
+## 1. Create a new skeleton flow
+
+Start by creating a new file to hold the logic of our flow:
+
+```bash
+$ touch lib/smart_answer_flows/example-smart-answer.rb
+```
+
+Open the new file in your editor and copy/paste this skeleton flow:
+
+```ruby
+module SmartAnswer
+  class ExampleSmartAnswerFlow < Flow
+    def define
+      name 'example-smart-answer'
+
+      value_question :question_1 do
+        next_node :outcome_1
+      end
+
+      outcome :outcome_1
+    end
+  end
+end
+```
+
+This flow contains a single question and a single outcome. Any non-empty response to `:question_1` will send you to `:outcome_1`.
+
+If you were to run `rails server` and visit http://localhost:3000/example-smart-answer at this point, you'd see an error that indicates that we need to add a landing page template.
+
+## 2. Create an ERB landing page template
+
+Create a new file for our landing page template.
+
+```
+$ mkdir lib/smart_answer_flows/example-smart-answer
+$ touch lib/smart_answer_flows/example-smart-answer/example_smart_answer.govspeak.erb
+```
+
+Although the landing page template needs to exist, it doesn't actually need to contain anything!
+
+Assuming you're still running `rails server`, visit http://localhost:3000/example-smart-answer and you should see the empty landing page of our new Smart Answer.
+
+Click "Start now" to visit the first question. You should see an error message indicating that we're now missing an ERB template for our question.
+
+## 3. Create an ERB question page template
+
+Create a new file for our question page template.
+
+```
+$ mkdir lib/smart_answer_flows/example-smart-answer/questions
+$ touch lib/smart_answer_flows/example-smart-answer/questions/question_1.govspeak.erb
+```
+
+Although the question page template needs to exist, it doesn't actually need to contain anything!
+
+Assuming you're still running `rails server`, visit http://localhost:3000/example-smart-answer and you should see an empty page containing a text field and a "Next step" button.
+
+Enter any value in the text field and click "Next step". You should see an error message indicating that we're now missing an ERB template for the outcome.
+
+## 4. Create an ERB outcome page template
+
+Create a new file for our outcome page template.
+
+```
+$ mkdir lib/smart_answer_flows/example-smart-answer/outcomes
+$ touch lib/smart_answer_flows/example-smart-answer/outcomes/outcome_1.govspeak.erb
+```
+
+Although the question page template needs to exist, it doesn't actually need to contain anything!
+
+Assuming you're still running `rails server`, visit http://localhost:3000/example-smart-answer and you should see an empty page containing a list of "Previous answers".
+
+And that's all there is to an incredibly simple Smart Answer.

doc/developing-without-vm.md

@@ -0,0 +1,13 @@
+# Developing without using the VM
+
+The simplest way to get Smart Answers running locally is to run:
+
+```bash
+$ PLEK_SERVICE_CONTENTAPI_URI=https://www.gov.uk/api \
+PLEK_SERVICE_STATIC_URI=https://assets-origin.preview.alphagov.co.uk \
+rails s
+```
+
+This tells Smart Answers to use the production Content API and the asset server from the preview environment.
+
+If you don't set either environment variable then the app will attempt to connect to the content API and asset server at http://contentapi.dev.gov.uk and http://static.dev.gov.uk respectively. NOTE. These are available automatically if you're [developing using the VM](developing-using-vm.md). If the app can't connect to these hosts then you'll see [errors](common-errors.md).

doc/development-principles.md

@@ -0,0 +1,27 @@
+# Smart Answer flows - Development principles
+
+## Do's
+
+* Make small improvements to the code before making even business-as-usual changes. See [refactoring existing Smart Answers](refactoring.md) for some common improvements.
+
+* Make use of the higher-level abstractions available in the project, for example the `DateRange`, `YearRange` and `TaxYear` classes.
+
+* Extract more higher-level abstractions where the same behaviour is being duplicated across multiple flows.
+
+* Model the domain of the policy/rules that make up a Smart Answer.
+
+* Ensure all policy logic is encapsulated in objects that are instantiated by (but separate from) the flow.
+
+* Ensure all presentation logic is kept in the ERB templates and associated helper methods.
+
+* Ensure the Smart Answer flows only contain routing (`next_node`) logic.
+
+* Iteratively develop new Smart Answers. Get a simply happy-path version deployed and build upon that in collaboration with the department and content team.
+
+## Dont's
+
+* Don't copy the style of existing "legacy" Smart Answers (e.g. [calculate-agricultural-holiday-entitlement](https://github.com/alphagov/smart-answers/blob/829837f1f738c711985bf3a7a5d1655605637edd/lib/smart_answer_flows/calculate-agricultural-holiday-entitlement.rb)).
+
+* Don't blindly follow the logic documents when creating/amending Smart Answers. This has lead to some of the problems we see in the "legacy" Smart Answers, e.g. policy logic being mixed up with flow/routing logic resulting in hard to maintain code.
+
+* Don't do big-bang development of new Smart Answers. See the point about iteratively developing them in the "Do's" section above.

doc/environments.md

@@ -0,0 +1,22 @@
+# Environments
+
+Smart Answers are available in Preview (e.g. [marriage-abroad][marriage-abroad-preview]), Staging (e.g. [marriage-abroad][marriage-abroad-staging]) and Production (e.g. [marriage-abroad][marriage-abroad-production]).
+
+## Preview
+
+Preview is deployed to automatically after a successful build of the master branch on Jenkins.
+
+Preview differs from Staging and Production in that it'll show draft Smart Answers and allow you to [display outcomes as Govspeak](viewing-templates-as-govspeak.md).
+
+## Staging
+
+Staging is deployed to manually during the [deployment process][deployment-doc]. We check that everything is working as expected before deploying to production.
+
+## Production
+
+Production is deployed to manually during the deployment process, once we're happy that the deployment to Staging has worked as expected.
+
+[deployment-doc]: deploying.md
+[marriage-abroad-preview]: https://www.preview.alphagov.co.uk/marriage-abroad
+[marriage-abroad-staging]: https://www.staging.publishing.service.gov.uk/marriage-abroad
+[marriage-abroad-production]: https://www.gov.uk/marriage-abroad

doc/erb-templates.md

@@ -0,0 +1,11 @@
+# ERB templates
+
+Content is defined in `content_for` blocks.
+
+Any state variable defined in the flow is available to be used in the ERB template. See [storing data](storing-data.md) for the various ways that you can set state variables.
+
+We remove all leading spaces from the content in the `content_for` blocks before processing it using Govspeak. This allows us to indent the content in the `content_for` blocks without having to worry about it affecting the generated HTML when it's processed using Govspeak.
+
+* [Landing page templates](landing-page-template.md)
+* [Question templates](question-templates.md)
+* [Outcome templates](outcome-templates.md)