Add documentation

diff --git a/LICENCE b/LICENCE
new file mode 100644 (file)
index 0000000..bb228bb
--- /dev/null
+++ b/LICENCE
@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-2018 David Llewellyn-Jones
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..867ff39
--- /dev/null
+++ b/README.md
@@ -0,0 +1,72 @@
+# Pedalo
+
+Measure your relative pedalo performance with others in a privacy-preserving way.
+
+Pedalo is a QT app for use with Sailfish OS.
+
+## Summary
+
+The Pedalo app allows you to measure your relative speed compared to others. Although originally designed for pedalo users on waterways, it could be used just as well to measure your performance in other cycling situations, such as when riding a bike.
+
+You use the app by recording details of each journey you make, but it's designed to be light on effort. Every time you start a journey click the Pedalo cover action. As you're cycling, keep mental track of the number of other cyclists you pass, and how many other cyclists pass you. At the end of your journey click the cover action again and enter the number of overtakers and overtakees. The app will record this data along with some other details such as how long you were cycling for.
+
+Carry on doing this over time and Pedalo will generate statistics about you, including what percentage of other cyclists you're faster/slower than.
+
+Pedalo stores all of the data it records on your device. No data gets stored in the cloud and no data is transmitted off the device. Pedalo is designed to protect your privacy, while still allowing you to compare your cycling with others.
+
+## Pedalo Rules, a history
+
+It's a little known fact that Birmingham has more canals than Venice. Because of this, back when I was a student in Birmingham it was natural to navigate around the city on pedalos, travelling on the canals.
+
+As students, we were also naturally quite competitive, but living in the technological dark-ages had no way to tell who was the fastest cyclist of the waterways. So we developed the Pedalo Rules.
+
+Every time we went on a journey we kept track of how many other pedalos we overtook, and how many overtook us. This allowed us to each calculate our speed relative to the other travellers on the canal.
+
+Naturally this approach applies not just to pedalos but to other forms of transport too. Nowadays, living in Cambridge, it's much more common to find myself on the back of a bicycle. So I use this app following the same Rules to keep track of my relative speed compared to other cyclists in the same way.
+
+## The Rules
+
+In order to get an accurate reflection of your relative speed, it's important to follow some common-sense rules.
+
+On each journey you need to keep a mental note of how many cyclists you overtake, and how many other cyclists overtake you. These are the numbers you need to enter into the app at the end of your journey.
+
+The rules are designed to allow you to keep track of these numbers in a sensible way.
+
+1. Throughout your journey you need to remember two numbers: how many cyclists you overtake (overtakees), and how many cyclists overtake you (overtakers).
+
+2. Don't count any overtakes that happen when you're at a junction, or slowing down for a junction.
+
+3. Only count overtakes with cyclists that are travelling on the same route and in the same direction as you.
+
+4. If you overtake a cyclist and add one to your 'overtakees' value, but they then overtake you back, subtract the value back off your 'overtakees' value, rather than adding it to your 'overtaken' value.
+
+5. Similarly if it happens the other way around.
+
+The master rule is that, whatever approach you use, try to be consistent and apply the same rules in the same way for people you overtake as you do for people who overtake you. Otherwise your statistics will end up biased.
+
+## Build from source
+
+If you want to build the application from source, you'll need the Sailfish SDK installed.
+
+Once you've cloned the repository locally, you'll need to execute the `generate.sh` script in order to create graphics in various resolutions for use in the app.
+
+You can then load the `harbour-pedalo.pro` project file into the Sailfish OS IDE (the Sailfish version of QT Creator) and can build the app normally from there.
+
+## Binary install
+
+The easiest way to install Pedalo is to download it from the Jolla Store.
+
+## Licence
+
+Pedalo is released under the MIT licence. See the LICENCE file for more detail.
+
+## Contact
+
+Feel free to contact me about the app. If you find bugs or have feature suggestions, please submit it as an issue.
+
+David Llewellyn-Jones
+
+david@flypig.co.uk
+
+http://www.flypig.co.uk?to=pedalo
+