(doc) adds troubleshooting section and cleans up doc