diff --git a/README.md b/README.md
index 31d3a89..3eb1427 100644
--- a/README.md
+++ b/README.md
@@ -5,17 +5,20 @@
 Easily add mutually exclusive fields to Django forms.
 ## Install
 ### PyPI
-```
+```shell
 pip install django-xor-formfields
 ```
 
 ### Source
-```
+```shell
 python setup.py install
 ```
 
 ## Example mutually exclusive form field (TextInput & Select):
-```
+```python
+from django import forms
+from xorformfields.forms import MutuallyExclusiveValueField, MutuallyExclusiveRadioWidget
+
 # with a widget inference
 MutuallyExclusiveValueField(
     fields=(forms.TypedChoiceField(choices=[(1,1), (2,2)], coerce=int),
@@ -30,26 +33,28 @@ MutuallyExclusiveValueField(
         ]))
 ```
 
-## Using FileOrUrlField
+## Using FileOrURLField
 This library also includes a more complete field that inherits from
-`MutuallyExclusiveValueField` that allows users to upload files via an URL or a
+`MutuallyExclusiveValueField` that allows users to upload files via a URL or a
 file upload. The field accepts a `to` parameter accepting the following values:
 `None, 'url', 'file'`. This value causes the field to perform either no
-normalization, normalizatoin to an url (by storing uploaded files as media) or
+normalization, normalization to a URL (by storing uploaded files as media) or
 to a file (by downloading urls to an `InMemoryUploadedFile`).
 ### Example:
-```
-FileOrUrlField(None) # returns UploadedFile objects or URL based on user input
-FileOrUrlField(to='file') # always validates to an UploadedFile
-FileOrUrlField(to='url', upload_to='foobar') # always validates to an URL
+```python
+from xorformfields.forms import FileOrURLField
+
+FileOrURLField(None) # returns UploadedFile objects or URL based on user input
+FileOrURLField(to='file') # always validates to an UploadedFile
+FileOrURLField(to='url', upload_to='foobar') # always validates to a URL
 ```
 #### AWS note:
-The `FileOrUrlField` supports a they keyword argument `no_aws_qs` which
+The `FileOrURLField` supports a keyword argument `no_aws_qs` which
 disables aws querystring authorization if using AWS via `django-storages`
 
 ## Tests & coverage!
 to run the tests simply run:
-```
+```shell
 DJANGO_SETTINGS_MODULE=xorformfields.test_settings django-admin.py test xorformfields
 ```
 
diff --git a/setup.py b/setup.py
index 0c6dfcf..9fd96fa 100644
--- a/setup.py
+++ b/setup.py
@@ -13,8 +13,9 @@
 
     version='0.1.0',
 
-    description='Mutually Exclusive form field wigets for Django',
+    description='Mutually Exclusive form field widgets for Django',
     long_description=long_description,
+    long_description_content_type='text/markdown',
 
     url='https://github.com/dschep/django-mutuallyexclusive-formfields',
 
diff --git a/xorformfields/forms/fields.py b/xorformfields/forms/fields.py
index 9b16ad1..62a168e 100644
--- a/xorformfields/forms/fields.py
+++ b/xorformfields/forms/fields.py
@@ -44,7 +44,7 @@ def clean(self, value):
         Only allows for exactly 1 valid value to be submitted, this is what
         gets returned by compress.
 
-        example to use directy (instead of using FileOrURLField):
+        example to use directly (instead of using FileOrURLField):
             MutuallyExclusiveValueField(
                 fields=(forms.TypedChoiceField(choices=[(1,1), (2,2)], coerce=int),
                         forms.IntegerField()))
@@ -108,10 +108,10 @@ class FileOrURLField(MutuallyExclusiveValueField):
 
     def __init__(self, to=None, *args, **kwargs):
         """
-        Accepts EITHER a file or an URL.
+        Accepts EITHER a file or a URL.
         The `to` parameter accepts 3 values:
             None: default to_python, returns either url or file
-            'file': if an url is submited, download it into an inmemory object
+            'file': if an url is submitted, download it into an in-memory object
             'url': uploads the file to default storage and returns the URL
         The`upload_to` param must be set when to='url'
         if using AWS, set no_aws_qs to disable querystring auth