diff --git a/README.md b/README.md
index 82affd7..52dad6a 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,11 @@
 # datalog-cpp
+
 implementation of datalog (without negation, and semi-naive bottom-up evaluation) in C++
 
 work-in-progress
 
 not yet alpha!
+
+## Documentation
+
+- [Quick git how to](./docs/git-how-to.md)
diff --git a/docs/git-how-to.md b/docs/git-how-to.md
new file mode 100644
index 0000000..210fc46
--- /dev/null
+++ b/docs/git-how-to.md
@@ -0,0 +1,92 @@
+# Quick git how to
+
+Quick instructions on how to contribute to this repo from the command line.
+
+Please see link to other resources below.
+
+## 1. Clone the repo on your local machine
+
+```
+git clone git@github.com:Z80coder/datalog-cpp.git
+```
+
+You should now have a `datalog-cpp` folder. 
+
+```
+cd datalog-cpp
+```
+
+## 2. Update the master branch
+
+
+```
+git checkout master
+git pull
+```
+
+## 3. Create a new branch for your work
+
+You will develop your code in your own branch. First you need to create it.
+
+```
+git checkout -b your_branch_name
+
+git push --set-upstream origin your_branch_name
+```
+
+## 4. Or switch to your existing branch for your work
+
+If you already done the step above, then ensure you are in your branch when you write code.
+
+```
+git checkout your_branch_name
+```
+
+## 5. Do some coding
+
+Work as normal
+
+## 6. Commit your changes
+
+Type
+```
+git status
+```
+to check which files you've added or changed. Note the files you want to commit at this time, then:
+```
+git add newfile1 newfile2
+```
+Then commit the changes
+```
+git commit
+```
+
+## 7. Push your changes to GitHub
+
+All you've done so far is declare some changes. You haven't yet pushed them to the GitHub repo. Let's do that now.
+
+```
+git push
+```
+
+You can keep adding, committing and pushing until you're ready to open a pull-request (with the intent of merging the changes in your branch into the `master` on the repo).
+
+## 8. Open a pull-request
+
+Go to https://github.com/Z80coder/datalog-cpp
+
+Click on the `Branch` button and look for `your_branch_name`, and then click on it.
+
+You should see a `New pull request` button. Click it and follow the user-interface prompts to create a pull-request.
+
+Once reviewed, your branch will be merged. You can contribute a new collection of changes by returning to `Create a new branch for your work` above.
+
+## Other resources
+
+- Microsoft Visual Studio has git support built in, and there's a GitHub plugin for Visual Studio to enable direct cloning from GitHub repos.
+
+- Microsoft Visual Code also has plug-in extensions that support Git
+
+- https://guides.github.com/ has some useful guides.
+
+- Also, there's a GitHub Desktop app: https://desktop.github.com/
\ No newline at end of file
diff --git a/src/Variable.h b/src/Variable.h
index 20d6b04..fa781bd 100644
--- a/src/Variable.h
+++ b/src/Variable.h
@@ -15,30 +15,47 @@ using namespace std;
 template <typename T>
 struct Variable : optional<T>
 {
+    /**
+     * @brief bind this variable to the supplied value (making it an unfree variable)
+     * 
+     * @param value
+     */
     void bind(const T &value)
     {
         this->emplace(value);
     }
 
+    /**
+     * @brief unbinds this variable (making it a free variable)
+     * 
+     */
     void unbind()
     {
         this->reset();
     }
 
+    /**
+     * @brief checks whether this variable is free or bound
+     * 
+     * @return true if bound to a value
+     * @return false if free
+     */
     bool isBound() const
     {
         return this->has_value();
     }
 
-    const T &
-    value() const
+    /**
+     * @brief returns the bound value (if not bound then throws an exception)
+     * 
+     * @return const T& 
+     */
+    const T &value() const
     {
         return this->optional<T>::value();
     }
 };
 
-// TODO: use auto more for return type of functions
-
 template <typename T>
 Variable<T> *var()
 {