Clairify README

Author: patch0

README.md

@@ -2,23 +2,36 @@
 
 This is a little application, written in [Ruby](https://ruby-lang.org), using the [Sinatra](https://sinatrarb.com/) framework.  It allows users to see the whereabouts of the International Space Station, using the [OpenNotify APIs](http://api.open-notify.org/).
 
+The aim of the exercise is for you to demonstrate how you would talk through your code and design decisions to peers, and will be used as a prompt for further discussions. We won't ask you to write any code during the interview itself, but we might ask specific questions about the code that you show us and how you might approach work on additional features or changes.
+
+It is important to attempt the all the tasks, even if you don't finish them.
+
+During the interview, you should be prepared to walk us through the code on your machine via screen share.
+
+If you get stuck, please do get in touch and we'll do our best to help.
+
 ## What we're expecting
 
-* You should spend 2-3 hours on this challenge, and attempt all three tasks.
-* Please send back your code by the end of Sunday 4th June, either as a link to a Github/Gitlab repo, or a zip/tar of your code.
+* You should spend no more than 3 hours on this challenge, and attempt all three tasks.
+* Please send back your code by the end of **Sunday 4th June**, either as a link to a Github/Gitlab repo, or as a zip file containing your code.
 
-We understand that you will have other commitments and time constraints, please let us know as soon as possible if you will be unable to complete this task by 4th June, so we are able to make allowances.
+We understand that you will have other commitments and time constraints, please let us know as soon as possible if you will be unable to complete this challenge by 4th June, so we are able to make allowances.
 
-It is important to attempt the tasks, even if you don't finish them.
+The challenge only needs to be runnable in a local environment; it doesn't need to be hosted anywhere.
 
-If you need help with the task, for whatever reason, please drop us an email and we will do our best to assist.
+If you need help with the challenge, for whatever reason, please do drop us an email and we will do our best to assist.
 
 ## Tasks
 
+Please do not spend any more than 3 hours completeing these tasks.
+
 1. Build a page to show the current astronauts that are in space, using the `OpenNotify#astros` method.
-2. Style the application using HTML and CSS to allow the information to be presented clearly.
-3. Add new endpoints, or modify the existing ones, to return the ISS position data as JSON, instead of an HTML page.
-   e.g. `http://localhost:4567/iss_position.json` should return JSON in the following format:
+  * Use the existing `position` page as a guide to when adding this new page.
+2. Add some style the application using HTML and CSS prioritising clear information presentation.
+  * Location data should be shown on the `position` page.
+  * Astronauts and their space ships could be shown in a table, or a list.
+  * Add a stylesheet and some simple CSS to make the layout really clear.
+3. Add new a new endpoint to return the ISS position data as JSON, instead of an HTML page.  `http://localhost:4567/iss_position.json` should return JSON in the following format:
 
 ```json
 {"iss_position": {"longitude": "-3.4941", "latitude": "-37.5113"}, "timestamp": 1684502291, "message": "success"}
@@ -28,7 +41,7 @@ If you need help with the task, for whatever reason, please drop us an email and
 
 Firstly you'll want to download and unzip the code into a directory or folder of your choice.
 
-Next if you've not already got Ruby, you'll need to [install it](https://www.ruby-lang.org/en/documentation/installation/).  There are a number of different ways to do it depending on your operating system.  **NB** Apple Macs already have it installed, but the version is quite old, so we'd recommend installing a more up-to-date one.
+Next if you've not already got Ruby, you'll need to [install it](https://www.ruby-lang.org/en/documentation/installation/).  There are a number of different ways to do it depending on your operating system.  The challenge needs **at least Ruby v3** to run.
 
 Once you've installed ruby, you can install the dependencies for this project in a terminal.  You should open a terminal in the directory or folder where your code has been checked out.
 
@@ -57,12 +70,16 @@ and you should be able to see it at http://localhost:4567.  **NB** When you make
 
 ## Useful documentation
 
+* Installing ruby on
+  * [MacOS using Homebrew](https://stackify.com/install-ruby-on-your-mac-everything-you-need-to-get-going/)
+  * [Windows using RubyInstaller](https://stackify.com/install-ruby-on-windows-everything-you-need-to-get-going/)
+  * [other OSs](https://www.ruby-lang.org/en/documentation/installation/)
 * [Getting started with Sinatra](https://sinatrarb.com/intro.html)
 * Various useful Ruby classes and modules:
   * [Array](https://ruby-doc.org/3.2.2/Array.html)
   * [Hash](https://ruby-doc.org/3.2.2/Hash.html)
   * [String](https://ruby-doc.org/3.2.2/String.html)
-  * [Comparable](https://ruby-doc.org/3.2.2/Comparable.html) (handy if you're sorting things)
+  * [Comparable](https://ruby-doc.org/3.2.2/Comparable.html) (handy if you're sorting things, e.g Hashes and Arrays)
   * [Enumerable](https://ruby-doc.org/3.2.2/Enumerable.html) (full of useful methods that both Hash and Array can use)
-* [ERB Templating](https://ruby-doc.org/3.2.2/stdlibs/erb/ERB.html)
+* [ERB Templating](https://ruby-doc.org/3.2.2/stdlibs/erb/ERB.html) (what we use in our views to execute Ruby)
 

open_notify.rb

@@ -3,14 +3,16 @@
 require 'json'
 require 'faraday'
 
-# Fetch data from the OpenNotify API service at
-# http://api.open-notify.org/
-#
-# To allow this to work without internet access, the read data method just
-# loads and parses the data
+# Fetch data from the OpenNotify API service at http://api.open-notify.org/
 module OpenNotify
   BASE_DIR = __dir__
 
+  # To allow this to work without internet access, the read data method just
+  # loads and parses the data
+  #
+  # Change this to 'yes' if you want to use the live data.
+  USE_LIVE_DATA = 'no'
+
   def iss_now
     fetch_data(api: 'iss-now')
   end
@@ -19,19 +21,17 @@ def astros
     fetch_data(api: 'astros')
   end
 
-  # This method would really fetch data from the live API, but for our
-  # purposes, a static file makes sense.
   def fetch_data(api:)
-    if ENV['USE_LIVE_DATA'] == 'yes'
+    if USE_LIVE_DATA == 'yes'
       conn = Faraday.new('http://api.open-notify.org/') do |f|
         f.response :json
       end
 
-      conn.get("#{api}.json").body
-    else
-      filepath = File.join(BASE_DIR, 'data', "#{api}.json")
-      JSON.parse(File.read(filepath))
+      return conn.get("#{api}.json").body
     end
+
+    filepath = File.join(BASE_DIR, 'data', "#{api}.json")
+    JSON.parse(File.read(filepath))
   end
 
   module_function :iss_now, :astros, :fetch_data