diff --git a/docs/README.joystick b/docs/README.joystick
new file mode 100644
index 0000000..03e6ec5
--- /dev/null
+++ b/docs/README.joystick
@@ -0,0 +1,16 @@
+The joystick should function on all compatible SDL platforms using the SDL
+input routines as well as on Linux using the kernel joystick API.  If you want
+to build with joystick support (enabled by default) then add --enable-joystick
+to the configure command line arguments.  Use --disable-joystick to build
+without joystick support.
+
+The joystick obeys the same freelook/strafe ruls as the mouse.  You can set
+these in the options menu.
+
+There are four cvars which can be set on the command line for the joystick:
+joystick_invert_y [1] if set to zero pulling back on the joystick points
+  the targeting recticle downwards
+joystick_axis_horz [0] sets the axis which controls left-right movement
+joystick_axis_vert [1] sets the axis which controls up-down movement
+joystick_throttle [3] sets the axis which controls the fore-backward motion
+  (if freelook is true)