Add troubleshooting guide.

README.md

@@ -27,3 +27,7 @@ which includes `:async` in its header-args.
 ## Development
 
 [Cask](https://github.com/cask/cask) manages dependencies and runs tests. Once Cask is installed, you can `make test`.
+
+## Troubleshooting
+
+First, go through the troubleshooting checklist, `troubleshooting.org`. It's an org-mode file in this repository that's designed to diagnose issues with ob-async. If that doesn't solve your problem, include a copy of the entire file (which will include your `#+RESULTS` blocks) in a Github issue.

troubleshooting.org

@@ -0,0 +1,77 @@
+#+TITLE: Issue Reporting Checklist
+#+PROPERTIES: :header-args :results value
+
+This checklist will help you diagnose problems with your =ob-async=
+setup.
+
+* Instructions
+
+Execute the src blocks one at a time with =ctrl-c ctrl-c= to
+ensure that =ob-async-org-babel-execute-src-block= is used for files
+with the :async header-arg. If by the end of this file your issue
+isn't solved, open an issue on Github with the contents of this file.
+
+First, make sure you can execute emacs-lisp src blocks *without* the
+async header argument. Otherwise you've got bigger problems, and none
+of this is going to work.
+
+#+BEGIN_SRC emacs-lisp
+(message "Yes, I can synchronously execute emacs-lisp from an org-babel src block.")
+#+END_SRC
+
+* Checklist
+
+Have you installed the =ctrl-c ctrl-c= hook as described in the
+README? If so, you should see =ob-async-org-babel-execute-src-block=
+in this list.
+
+#+BEGIN_SRC emacs-lisp :results value
+(message "%s" org-ctrl-c-ctrl-c-hook)
+#+END_SRC
+
+From where are you loading =ob-async=?
+
+#+BEGIN_SRC emacs-lisp
+(symbol-file 'ob-async-org-babel-execute-src-block)
+#+END_SRC
+
+#+BEGIN_SRC emacs-lisp
+(message "PID: %s\nEmacs version: %s\norg version: %s\nPath to org: %s" (emacs-pid) (emacs-version) (org-version) (symbol-file 'org-version))
+#+END_SRC
+
+Execution of the :async block occurs in an Emacs subprocess. Are you
+using a consistent version of emacs and org-mode across both
+processes? Compare the output of this block the output of the previous block.
+
+#+BEGIN_SRC emacs-lisp :async
+(message "PID: %s\nEmacs version: %s\norg version: %s\nPath to org: %s" (emacs-pid) (emacs-version) (org-version) (symbol-file 'org-version))
+#+END_SRC
+
+If you're using a consistent version and still facing problems, turn
+on async debugging.
+
+#+BEGIN_SRC emacs-lisp
+(setq async-debug t)
+#+END_SRC
+
+If possible, replace the following block with a block that reproduces
+your problem, then execute it.
+
+#+BEGIN_SRC emacs-lisp :async
+(message "I'm executed in a subprocess.")
+#+END_SRC
+
+This is the elisp that was sent to the Emacs subprocess. If there's
+still nothing obviously wrong, file an issue on GitHub and include the
+contents of this file as a Gist.
+
+#+BEGIN_SRC emacs-lisp
+  (switch-to-buffer "*Messages*")
+  (goto-char (point-max))
+  (re-search-backward "Transmitting sexp {{{\\([^}]+\\)}}}")
+  (match-string 1)
+#+END_SRC
+
+* Bug Description
+
+If your issue still hasn't been resolved, describe it here.