diff --git a/README.md b/README.md
index 6ce8908..2e0ee2d 100644
--- a/README.md
+++ b/README.md
@@ -79,8 +79,8 @@ class Album(ormar.Model):
     # note that type hints are optional so 
     # id = ormar.Integer(primary_key=True) 
     # is also valid
-    id = ormar.Integer(primary_key=True)
-    name = ormar.String(length=100)
+    id: int = ormar.Integer(primary_key=True)
+    name: str = ormar.String(max_length=100)
 
 
 class Track(ormar.Model):
@@ -89,10 +89,10 @@ class Track(ormar.Model):
         metadata = metadata
         database = database
 
-    id = ormar.Integer(primary_key=True)
-    album = ormar.ForeignKey(Album)
-    title = ormar.String(length=100)
-    position = ormar.Integer()
+    id: int = ormar.Integer(primary_key=True)
+    album: Optional[Album] = ormar.ForeignKey(Album)
+    title: str = ormar.String(max_length=100)
+    position: int = ormar.Integer()
 
 
 # Create some records to work with.
diff --git a/docs/index.md b/docs/index.md
index 6ce8908..2e0ee2d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -79,8 +79,8 @@ class Album(ormar.Model):
     # note that type hints are optional so 
     # id = ormar.Integer(primary_key=True) 
     # is also valid
-    id = ormar.Integer(primary_key=True)
-    name = ormar.String(length=100)
+    id: int = ormar.Integer(primary_key=True)
+    name: str = ormar.String(max_length=100)
 
 
 class Track(ormar.Model):
@@ -89,10 +89,10 @@ class Track(ormar.Model):
         metadata = metadata
         database = database
 
-    id = ormar.Integer(primary_key=True)
-    album = ormar.ForeignKey(Album)
-    title = ormar.String(length=100)
-    position = ormar.Integer()
+    id: int = ormar.Integer(primary_key=True)
+    album: Optional[Album] = ormar.ForeignKey(Album)
+    title: str = ormar.String(max_length=100)
+    position: int = ormar.Integer()
 
 
 # Create some records to work with.
diff --git a/docs_src/models/docs005.py b/docs_src/models/docs005.py
index cd0fa9d..5359606 100644
--- a/docs_src/models/docs005.py
+++ b/docs_src/models/docs005.py
@@ -50,7 +50,7 @@ Will produce:
  'name': mappingproxy({'allow_blank': False,
                        'autoincrement': False,
                        'choices': set(),
-                       'column_type': String(length=100),
+                       'column_type': String(max_length=100),
                        'curtail_length': None,
                        'default': None,
                        'index': False,