Create a debugging/troubleshooting guide

[abingham]

A nice guide explaining the basic troubleshooting steps would be very helpful. Things like:

• Make sure you have the latest server and client
• Look for suspicious things in *ycmd-server*
• Enable logging and look at the output. osv...

[renewagner]

A few more suggestions for troubleshooting hints I originally brought up in #466:

• Incorrect flags passed to ycmd/libclang are one of the most common sources of completion failures or ycmd issures in general .
• libclang lacks a default include search path although all Clang command line tools do have one. Thus, even if code compiles fine when passing the user-specified flags to clang on the command line it may not compile with libclang due to missing include search path entries. These can be obtained by parsing clang or gcc output and passed on to ycmd/libclang via .ycm_extra_conf.py. An example of such functionality can be found in the LoadSystemIncludes() function from the emacs-ycmd test suite.
• Users should verify that the flags listed in ycmd-show-debug-info exactly match their expectations. Particulary, that all system include paths are present.
• Instead of the vim command :YcmDiags one can install flycheck and flycheck-ycmd to receive diagnostics (compiler error and warning messages) from ycmd. Many configuration errors will become apparent this way. E.g., if there are undefined types although the corresponding #include directive is present this is a strong indication that the include search path passed to ycmd is incomplete.