diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8a1d377..ab8a2a4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -56,6 +56,9 @@ This is probably one of (if not the) biggest things in this release.
 user input, exit code, and error. User input has been added to the return to
 account for runners wanting to prompt for continued input, and to add it
 properly to history.
+- **Breaking Change:** Job objects and timers are now Lua userdata instead
+of a table, so their functions require you to call them with a colon instead
+of a dot. (ie. `job.stop()` -> `job:stop()`)
 - All `fs` module functions which take paths now implicitly expand ~ to home.
 
 ### Fixed
diff --git a/docs/jobs.txt b/docs/jobs.txt
index 1dc8009..a5fee9c 100644
--- a/docs/jobs.txt
+++ b/docs/jobs.txt
@@ -20,8 +20,11 @@ and `execPath` is an absolute path for the command executable.
 - `disown(id)`: Removes a job by ID from the job table.
 
 # Job Object
-A job object on the Lua side is a table with some functions.
-On the under side it represents a job in the job table.
+A job object is a piece of `userdata`. All the functions of a job require
+you to call them with a colon, since they are *methods* for the job object.
+Example: hilbish.jobs.last():foreground()
+Which will foreground the last job.
+
 You can still have a job object for a disowned job,
 it just won't be *working* anywhere. :^)
 
diff --git a/docs/timers.txt b/docs/timers.txt
index c5a456b..0f89718 100644
--- a/docs/timers.txt
+++ b/docs/timers.txt
@@ -16,9 +16,17 @@ a timer via ID.
 when the timer is triggered.
 
 # Timer Object
-Those previously mentioned functions return a `timer` object, to which you can
-stop and start a timer again. The functions of the timers interface also
-return a timer object.
+All those previously mentioned functions return a `timer` object, to which
+you can stop and start a timer again.
+
+An example of usage:
+local t = hilbish.timers.create(1, 5000, function()
+	print 'hello!'
+end)
+
+t:stop()
+print(t.running, t.duration, t.type)
+t:start()
 
 ## Properties
 - `duration`: amount of time the timer runs for in milliseconds