"Troubleshooting" article type best practices

Contributors Contributors 作成日:
この記事はまだ翻訳されていません。すでに SUMO のローカライズ方法を知っている場合は、この記事を翻訳してください。SUMO の記事を翻訳する方法を学びたい場合は、記事翻訳の手引きをご覧ください

"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

この記事は役に立ちましたか?

しばらくお待ちください...

以下の人々がこの記事の執筆を手伝ってくれました:

Illustration of hands

ボランティア

あなたの専門知識を成長させ、他の人と共有してください。質問に答えたり、ナレッジベースを改善したりしてください。

詳しく学ぶ