Improvements to documentation

README.md

@@ -1,18 +1,51 @@
 #Work RPG (tentative title)
 
-Webapp backend for an idea on how to reward work.  Using an RPG like system of giving
-experience and leveling up people for their roles (or classes) based on accomplishments
-during their work.
+Webapp backend for an idea on how to reward work.  Using an RPG like system of
+giving experience and leveling up people for their roles (or classes) based on
+accomplishments during their work.  For a better outline of the project, check out
+the (docs)[docs/intro.md].
 
 ##Technical stuff
 
-Written (to start) to use Flask and Mongo.  It will provide a RESTful API to handle
-the actions involved with handling tracking and rewarding players.
+The app is written using Python 2.7 with Flask for the web framework and MongoDB as
+the database backend.  It will provide an adaptive RESTful API along with a simple
+backend generated HTML interface (to start).  It is written to use virtualenv.  It
+will be done with good test coverage and against the flake8 (pyflakes + PEP8)
+linting utility.
 
 ##Setup
 
-Use virtualenv (it is such a good thing to do)
+For setup, if you have virtualenvwrapper and make installed you can just run:
 ```
 make init
 ```
-Configure using the rpg/settings.py file
+
+For those who do not, you can make a virtualenv (I recommend something like .env or
+venv), activate it, then pip install the requirements, copy the template settings
+file (described below), and it should be good to go.  (I would like to write a
+better setup script, probably a setup.py file at some point).  So for Linux:
+```
+virtualenv .env
+source .env/bin/activate
+pip install -r requirements.txt
+cp rpg/settings.py_template rpg/settings.py
+python serve.py
+```
+
+## Settings
+
+The app settings live in the rpg/settings.py.  I have included a
+(template)[rpg.settings.py_template].  The file holds various settings for how the
+application should behave, more settings will be added as functionality and
+features get added (like when I get around to making the logging at a production
+level capacity).  The current settings are:
+* **DEBUG** straight forward, boolean that enables debugging settings
+* **SECRET_KEY** this is a string that is used as part of the salt in password
+  hashes
+* **MONGO_HOST** dictionary that describes the URI of the mongodb instance to be
+  used, keys are 'host' (the address of the machine) and 'port' (the port the
+  service is listening on)
+* **DEFAULT_SESSION** dictionary (temporary for now) that defines the defaults for
+  a newly created session, mostly will be things like the default number of items
+  returned for large lists (paginated) and the default datetime format.  (nothing
+  for now)

docs/intro.md

@@ -9,3 +9,21 @@ functionality.
 ## Table of Contents
 1. [Login](login.md)
 1. [Players](players.md)
+
+## Terminology
+* **Player**: The 'game' unit, this is the alter ego that plays the game, their are
+the hero for a certain person.  The player will go on quests (see below), accumulate
+experience, and level up.
+* **User**: The credential based login attached to a real person.  This is a
+detachment from the player only in that there are going to be people who will
+participate in the game without having a player character such as DMs (see below).
+* **Dungeon Master (DM)**: These are users that will not have a player but are instead
+in charge of managing the game itself.  They will award quests, items, manage the
+available quests, handle tweaking the class system, etc.
+* **Quest**: This is a real world task or accomplishment that has attached rewards,
+such as experience, items, currency, etc.  These will be determined and outlined by
+the DMs and performed by the players.
+* **Items**: Some perk boosting rewards for quests, they will be able to modify the
+rewards from other quests when equipped.
+* **Class**: This will be attached to skill areas in the real world, things that
+pertain to various specialities and will affect the rewards from quests.

docs/login.md

@@ -1,3 +1,13 @@
 # Login System
 
 The login system is the stuff that entails logging in/out and registering.
+
+## Permissions
+
+So every user should have specific permissions, the two main scenarios would be:
+* The 'admin' performs actions in regards to other players such as giving exp,
+  items, etc.  Admins should be the only ones who can reward players.
+* The 'player' who is really just able to see their current player (the former is
+  the user whose only permission is their player) and manage them.  They will be
+  able to change classes, change the name, mess with items and appearance.
+

docs/players.md

@@ -1,4 +1,21 @@
 # Players
 
 Players are the unit that actually participate.  They are what tracks the changes
-in experience, leveling, etc.
+in experience, leveling, etc.  Players are the main action origin of the system,
+they are what perform quests, get items, accumulate exp.  The users log in to
+manage their player(s).
+
+## Properties
+
+Players will have properties for their class(es), a counter for their total exp,
+a log of their quests, an inventory and track what of that inventory is equiped.
+The player model will need to track all of these things (and more as features and
+concepts get added/implemented).
+
+* Name
+* Attached Login
+* Experience
+* Class
+* Inventory
+* Equipped
+* Quests

rpg/settings.py_template

@@ -1,8 +1,8 @@
-DEBUG = True
-SECRET_KEY = "onpeakrpggamebitches"
+DEBUG = True # change to False for a Prod environment or you don't want the debug helpers
+SECRET_KEY = "ChangeMeIShouldBeASecret" # change, should be unique to your instance
 MONGO_HOST = {
-    "host": "localhost",
-    "port": 27017
+    "host": "localhost", # Address of the machine hosting the service
+    "port": 27017 # Port service is listening on (default: 27017)
 }
 DEFAULT_SESSION = {
 }