Improve Error Handling and Troubleshooting Documentation

[DenicaGo]

Description

Context: The onboarding process for new implementers has proven to be challenging so user research was done with early implementers to address any obstacles by identifying and analysing areas for improvement within the onboarding experience.

Research finding: Participants noted that error messages are often vague, and troubleshooting steps are not always included in the documentation. Providing clear instructions for resolving issues would help users work through challenges independently.

User story: As a user, I want clear error messages and troubleshooting steps for common issues, so that I can quickly resolve problems without needing to escalate to support.

Acceptance Criteria

• Error messages are specific and descriptive, detailing the problem rather than using vague terms like "An error occurred."
• Each error message includes clear, actionable steps that users can follow to resolve the issue.
• A searchable index of error codes and common issues with their fixes is available in the documentation or knowledge base for quick lookup.
• A section listing frequent issues, their causes, and solutions is available in the documentation.
• If an issue requires time to resolve, users are given an estimated resolution time or alternative steps to follow.
• Clear instructions are provided for users to escalate issues if they cannot resolve the problem on their own.
• If feasible
  • Links to relevant documentation, FAQs, or troubleshooting guides are provided within the error message for easy access.
  • Error messages and troubleshooting guides are updated regularly based on user feedback and common issues.

Impacted sections

UNTP Spec:
GitHub repo - https://github.com/uncefact/spec-untp
Website - https://uncefact.github.io/spec-untp/
Reference Implementation/Testing:
GitHub repo - https://github.com/uncefact/tests-untp
Website - https://uncefact.github.io/tests-untp/
Demo Instance - https://untp.showthething.com/
Playground - https://test.uncefact.org/untp-playground

Related tickets

Create a resource hub #281