Merge pull request #188 from foodcoops/doc_fixups

Several documentation fixups [ci skip]

README.md

@@ -9,10 +9,66 @@ Web-based software to manage a non-profit food coop (product catalog, ordering,
 
 More information about using this software and contributing can be found on the [wiki](https://github.com/foodcoops/foodsoft/wiki).
 
-Install
+System requirements
---------
+-------------------
 
-Have a look at [DEVELOPMENT](https://github.com/foodcoops/foodsoft/blob/master/doc/DEVELOPMENT) (possibly outdated) and the (more recent) [Developing Guidelines](https://github.com/foodcoops/foodsoft/wiki/Developing-Guidelines) page on the wiki.
+* [RVM](https://rvm.io/rvm/install)
+* [Ruby 1.9.3](https://www.ruby-lang.org/en/downloads/)
+* [Bundler](http://bundler.io/)
+
+Getting started
+---------------
+
+1. Install RVM (if you have not done so before):
+
+       \curl -L https://get.rvm.io | bash
+
+2. Clone the repository from GitHub:
+
+       git clone https://github.com/foodcoops/foodsoft.git
+
+3. Install Ruby dependencies:
+
+       bundle install
+
+4. Setup your development environment:
+
+       rake foodsoft:setup_development
+
+   This will interactively prompt with several questions relating to your
+   required environment.
+
+5. Start rails by running:
+
+       bundle exec rails s
+
+6. Open your favorite browser and open the web application at:
+
+       http://localhost:3000/
+
+   You might want to watch a
+   [kitten video](https://www.youtube.com/watch?v=9Iq5yCoHp4o)
+   while it's loading.
+
+7. Login using the default credentials: `admin/secret`
+
+8. Change the admin password, just in case.
+
+9. Have phun!
+
+Developing
+----------
+
+Have a look at [DEVELOPMENT.md](https://github.com/foodcoops/foodsoft/blob/master/doc/DEVELOPMENT.md) (outdated) and the (more recent) [Developing Guidelines](https://github.com/foodcoops/foodsoft/wiki/Developing-Guidelines) page on the wiki.
+
+Deploying
+---------
+
+As you might have noticed, documentation is scarce and insufficient. If you
+intend to deploy foodsoft in production, we would love to guide you through
+the process. We can be contacted through the
+[developers@foodcoop.nl](mailto:developers@foodcoop.nl) or
+[foodsoft@foodcoops.net](mailto:foodsoft@foodcoops.net).
 
 License
 -------

doc/DEPLOYMENT.md

@@ -20,4 +20,4 @@ Deploy to staging
   bundle exec cap deploy
 
 Deploy to production
-  bundle exec cap production deploy
+  bundle exec cap production deploy

doc/DEVELOPMENT.md

@@ -15,7 +15,7 @@ Create the database configuration from the default:
 If you are fine with using a file-based sqlite database you are all set.
 The sqlite files (development/test/production) will reside in the "db" directory.
 Otherwise you would want to edit database.yml to suit your needs (MySQL whatever).
-	
+
 
 (2) Configure development environment
 -------------------------------------
@@ -66,7 +66,7 @@ With this, you also get a ready to go user with username 'admin' and password 's
 
 
 (7) Try it out!
----------------	
+---------------
 Start the WEBrick server to try it out:
 
 	bundle exec rails s
@@ -93,4 +93,4 @@ Just install mailcatcher with gem install mailcatcher and start the service with
 
 From now on you have a smpt server listening on 1025. To see the emails go to
 
-    http://localhost:1080
+    http://localhost:1080

doc/README_FOR_APP.md

@@ -3,30 +3,30 @@ Run "rake doc:app" to generate API documentation for your models and controllers
 
 = The Foodsoft
 
-is a Web-based software to manage a non-profit food coop (product catalog, ordering, accounting, job scheduling). 
+is a Web-based software to manage a non-profit food coop (product catalog, ordering, accounting, job scheduling).
 
 
 == Bestellen
-Das Bestellen ist der Hauptteil dieser Software und ein wenig kompliziert. 
+Das Bestellen ist der Hauptteil dieser Software und ein wenig kompliziert.
-Hier starte ich den Versuch die Programmlogik in Text umzusetzen und 
+Hier starte ich den Versuch die Programmlogik in Text umzusetzen und
 verweise auf die enstprechenden Controller bzw. Modelle.
 Der relevante Controller ist OrderingController.
 
 === Bestellung "in Netz stellen"
 Darunter verstehen wir die Auswahl von Artikeln eines bestimmten Lieferanten fuer eine zeitlich begrenzte
 Bestellung im Internet. Die relevanten Methoden sind OrdersController#newOrder und folgende.
-Jede Bestellung wird durch die Klasse Order abgebildet. 
+Jede Bestellung wird durch die Klasse Order abgebildet.
 
 Die zugehoerigen Artikel werden duch die Klasse OrderArticle mit den Artikeln verknuepft.
 Dabei werden auch die Attribute quantity, tolerance und quantity_to_order gespeichert.
 Diese Mengen repraesentieren die Gesamtbestellung, also alle Bestellgruppen.
 
 === Eine Bestellgruppe bestellt...
-Die Methode OrdersController#order schickt uns die Bestellenseite. Mit dieser Oberflaeche 
+Die Methode OrdersController#order schickt uns die Bestellenseite. Mit dieser Oberflaeche
 koennen die Bestellgruppena die vorher ausgewaehlten Artikel bestellen.
-Mittels den Buttons werden dabei live, also clientseitig, die Preise ermittelt 
+Mittels den Buttons werden dabei live, also clientseitig, die Preise ermittelt
 und der Gesamtpreis berechnet. Ist der Gesamtpreis groeßer als der aktuelle
-Gruppenkontostand, so wird die Preisspalte rot unterlegt und die Bestellung 
+Gruppenkontostand, so wird die Preisspalte rot unterlegt und die Bestellung
 kann nicht gespeichert werden.
 
 === (gruppen)-Bestellung wird gespeichert
@@ -67,27 +67,27 @@ Wir unterscheiden dehalb zwei Faelle:
   Verringe Bestellung auf 2(1) um 19uhr.
   => Zeile mit created_on = 18uhr wird gelöscht und
   in der Zeile mit created_on = 17uhr wird der Wert tolerance auf 1 gaendert.
-  
+
 === Wer bekommt wieviel?
 
 Diese Frage wird wie schon erwaehnt mittels der group_order_article_quantites -Tabelle
-geloest. 
+geloest.
 Beipspiel.
   articel x mit unit_quantity = 5.
   17uhr: gruppe a bestellt 2(3), weil sie auf jeden fall was von x bekommen will
   18uhr: gruppe b bestellt 2(0)
   19uhr: gruppe a faellt ein dass sie doch noch mehr braucht von x und aendert auf 4(1).
-  
+
   jetzt gibt es drei zeilen in der tabelle, die so aussehen:
   (gruppe a), 2(1), 17uhr (wurde um 19uhr von 2(3) auf 2(1) geaendert)
   (gruppe b), 2(0), 18uhr
   (gruppe a), 2(0), 19uhr.
-  
+
   die zuteilung wird dann wie folgt ermittelt:
   zeile 1: gruppe a bekommt 2
   zeile 2: gruppe b bekommt 2
   zeile 3: gruppe a bekommt 1, weil jetzt das gebinde schon voll ist.
-  
+
   Endstand: insg. Bestellt wurden 6(1)
   Gruppe a bekommt 3 einheiten.
   gruppe b bekommt 2 einheiten.