Troubleshooting guides

Fixing problems


Answers what the common problems are, and how to check for them? Tends to start small and grow as use of the software reveals how it might break.


  • Offer places where people can ask and report problems (forum, issue page, help desk)

  • Collect enough information to replicate the issue

  • Customize logs for actionable insight

  • Create useful error messages at the source-code level

  • Don’t mistake symptoms for root cause

  • Implement a comprehensive logging infrastructure and use correlation IDs

  • Use system monitors and predictive analytics

  • Publish relevant resolutions and fixes in troubleshooting guides