Skip to content

PROPOSAL: Troubleshooting Articles aligned with Product Documentation

Request for comments

Need

 Troubleshooting should be integrated into knowledge articles because it transforms static documentation into actionable resources that genuinely help Customers resolve issues without the need for support. .

  • When knowledge articles include troubleshooting sections, they address the reality that things don't always go as planned. 
  • By anticipating common issues and providing clear resolution steps, we can prevent customers from getting stuck and reduce the volume of support tickets.
  • Troubleshooting sections improve the user experience by keeping solutions centralized.
  • Instead of forcing users to search through multiple resources or contact support, they can find answers in one location. This creates a more efficient self-service experience.

Troubleshooting can be and should be in both documentation and knowledge articles, but with different approaches and purposes for each.

In documentation, troubleshooting belongs as integrated sections within procedural guides. Allows Customers to actively follow instructions and encounter problems. It's contextual troubleshooting that addresses issues specific to the task at hand - like "If the installation fails at step 3, try this" or "If you don't see the expected output, check that."

In knowledge articles, troubleshooting works better as standalone, comprehensive resources that address broader issues or common problems that span multiple procedures. 

  • These are typically more detailed and cover symptoms, root causes, and multiple resolution paths. Knowledge articles are ideal for complex troubleshooting scenarios that don't fit neatly into a single procedural document.

Documentation troubleshooting is immediate and task-specific, while knowledge article troubleshooting is comprehensive and can be referenced across multiple scenarios

Proposed Solution

Align Product Documentation and Knowledge Articles to deliver consistent troubleshooting details across both doc and KB, creating a seamless customer experience that promotes effective self-service and reduces support tickets..

  • Implement consistent troubleshooting formats across both documentation and knowledge articles
    • Docs to continue to add Troubleshooting (Link to knowledge for reference)
    • Knowledge articles to add Troubleshooting for specific issues (and link to docs for reference)
  • Enhance cross-linking and search capabilities between documentation and knowledge base (using reference links) 
  • Establish processes that ensure updates are reflected in both KB and docs.

Actions: 

  • Inventory existing troubleshooting content in both product documentation and knowledge articles
  • Engage product documentation team *
  • Establish structure for ongoing alignment
  • Develop troubleshooting content templates and style guidelines *
  • Define content structure for both KB and Docs (That align) *
  • Design cross-referencing and linking strategies *
  • Develop maintenance and update reviews
  • Establish seamless linking between documentation and knowledge articles *
  • Make sure we have consistent tagging and categorization
Edited by Kirsty Allen