"Troubleshooting" article type best practices

"Troubleshooting" articles address “How do I fix...?” questions that arise when users encounter problems with our products, services, or features. These articles guide users through identifying, diagnosing, and resolving common issues, providing clear and concise solutions. Unlike "About" or "How-to" articles that introduce or explain how to use Mozilla's offerings, "Troubleshooting" articles delve into solving specific problems, ensuring users can get back to a seamless experience as quickly as possible.

When to write a "Troubleshooting" article

Consider creating a "Troubleshooting" article when:

• Users frequently encounter a specific issue with a product, service, or feature.
• There’s a known problem that may not be intuitive for users to solve on their own.
• An update, change, or bug introduces new challenges that users need help navigating.

Best practices for writing "Troubleshooting" articles

• Identify the issue: Start by clearly stating the problem. This helps users know they’re in the right place and that the article addresses the issue they’re experiencing.
• Explain the cause: Where possible, briefly explain why the issue occurs. Understanding the cause can help users prevent future occurrences.
• Provide step-by-step instructions: Break down the resolution process into clear, manageable steps.

Article structure

• Title: The title should match what the article is about and what the user is searching for. Troubleshooting article titles should start with an action-verb, but avoid using gerunds. You should also avoid using article titles containing “How to…”. Try to use the keywords “Fix” or “Resolve” in your title and use sentence-style capitalization for articles. “How-to” titles should be task oriented, while “Troubleshooting” titles should be problem-centric. Limit your title to around 60 characters, as Google typically displays the first 50–60 characters of a title tag.
• Summary: This section describes the specific problem or symptoms users may encounter. It should be written in clear and concise language, avoiding technical jargon whenever possible, to ensure it's accessible to a wide audience. Include keywords such as “can’t”, “unable to”, “not working”, “crashing”, etc to help with SEO.
• Body content: The body contains the breadth and depth of information required to diagnose and resolve the problem. It may also contain results and examples. Add a Table of Contents section at the beginning of the article if you’re documenting multiple sets of related steps. Use H2 for section headings. Lead with the objective before documenting the steps (i.e. “Reset your Firefox printer settings”).
  • Pre-requisite: This helps users understand the underlying factors contributing to the issue. Add any information or actions the user should know or do prior to attempting to troubleshoot the issue.
  • Context (optional): Add any conceptual information or common reasons why the problem might occur.
  • Steps: Use ordered lists to document the steps and actions that must be taken to diagnose and resolve the problem. Lead with the objective before documenting the steps. Avoid using nested steps.
  • Result (optional): Add the expected outcome after completing the set of steps.
  • Example (optional): Add any examples to support the task.
  • Post-requisite (optional): Add any information the user needs to know or do after completing the task.
• Learn more links: Use H3 for the Learn More section header. It shouldn’t be included in the table of contents. Add unordered lists for the Learn more links and don’t add more than four links to this section.

Examples

• Fix printing problems in Firefox