Troubleshooting article template

Overview

Troubleshooting articles allows perfect document solutions for commonly encountered problems. A straight-forward, concise article can quickly guide customers to fast problem resolution.

Scaffolding live template creates a consistent format for your troubleshooting articles to increase effectiveness and ease of use.

The template helps you to structure the basic requirements such as

defining the problem
listing the affected environments
stating the cause
explaining the solution
displaying related articles

How to use the Troubleshooting article template

Step 1 - Describe the problem

As specifically as possible, describe the problem being addressed in this troubleshooting article.

This will help readers determine if this article will apply to the problem they are trying to resolve. Consider the issue from your audience's perspective and explain it using terminology and examples that are relevant and easy to understand.

Clearly outline what isn't working and include the symptoms for diagnosis in the Text Data macro.

Step 2 - Add environment details

Describe which system(s) in the environment have been affected by the problem.

Select one or more options from the List Data macro.

It's important to include details so readers can check against the specifics of their environment's setup.

Step 3 - Describe the cause

By explaining why the problem occurred (its root cause), the reader will gain a deeper understanding of the issue and reduce the likelihood of the same error occurring in the future.

Step 4 - Provide a step-by-step solution

Now that you’ve described the problem and why it occurred, it’s time to explain how to fix it.

Write a detailed but concise step-by-step guide in the Repeating Data macro to guide readers through problem resolution.

Remember to use terms that are familiar to your readers, don't make assumptions about what your reader knows, and include each step of the process.

Step 5 - Display related articles

Sharing articles related to the troubleshooting issue at hand can further assist your reader.

To do this, simply search (with autocomplete) and link related articles through List Data macro.

Ingredients

Apps	Scaffolding Forms & Templates
Hosting platform	Server, Data Center

Code

<ac:layout>
  <ac:layout-section ac:type="two_right_sidebar">
    <ac:layout-cell>
      <h1>Problem</h1>
      <ac:structured-macro ac:macro-id="6f5789f6-a53f-42f9-a24a-efcae9735679" ac:name="hidden-data" ac:schema-version="1">
        <ac:parameter ac:name="whenNotEmpty">Problem</ac:parameter>
        <ac:parameter ac:name="atlassian-macro-output-type">INLINE</ac:parameter>
        <ac:rich-text-body>
          <p>
            <span style="color: rgb(165,173,186);">
              <em>What didn't work? Add a short description of the problem and symptom in this <a class="external-link" href="https://docs.servicerocket.com/scaffolding/macro-reference/text-data" rel="nofollow" style="text-decoration: none;">Text Data</a> macro.</em> </span>
          </p>
        </ac:rich-text-body>
      </ac:structured-macro>
      <ac:structured-macro ac:macro-id="d3ecf24e-b31a-4434-a142-7dcc2d8ccb53" ac:name="text-data" ac:schema-version="1">
        <ac:parameter ac:name="name">Problem</ac:parameter>
        <ac:parameter ac:name="atlassian-macro-output-type">INLINE</ac:parameter>
        <ac:rich-text-body>
          <p>
            <br/>
          </p>
        </ac:rich-text-body>
      </ac:structured-macro>
    </ac:layout-cell>
    <ac:layout-cell>
      <ac:structured-macro ac:macro-id="e6130ed0-3486-4947-96a0-c2d46526ce1c" ac:name="info" ac:schema-version="1">
        <ac:parameter ac:name="title">Can't find what you need?</ac:parameter>
        <ac:rich-text-body>
          <p>Send us an e-mail at <a href="mailto:apps.support@servicerocket.com">apps.support@servicerocket.com</a> for assistance.</p>
        </ac:rich-text-body>
      </ac:structured-macro>
    </ac:layout-cell>
  </ac:layout-section>
  <ac:layout-section ac:type="two_right_sidebar">
    <ac:layout-cell>
      <h1>Environment</h1>
      <ac:structured-macro ac:macro-id="c270d9f7-d86e-437c-a44d-9b5a06ab31bc" ac:name="hidden-data" ac:schema-version="1">
        <ac:parameter ac:name="whenNotEmpty">System</ac:parameter>
        <ac:parameter ac:name="atlassian-macro-output-type">INLINE</ac:parameter>
        <ac:rich-text-body>
          <p>
            <span style="color: rgb(165,173,186);">
              <em>Which system and add-on that are affected? Select one or more options from this <a href="https://docs.servicerocket.com/display/SCAF/List+Data">List Data</a> macro.</em> </span>
          </p>
        </ac:rich-text-body>
      </ac:structured-macro>
      <table class="relative-table wrapped" style="width: 86.1736%;">
        <colgroup> <col style="width: 23.9103%;"/> <col style="width: 76.0897%;"/> </colgroup>
        <tbody>
          <tr>
            <th>System</th>
            <td>
              <div class="content-wrapper">
                <ac:structured-macro ac:macro-id="e911a6b6-2241-4516-a7e4-2d0a084b3d44" ac:name="list-data" ac:schema-version="1">
                  <ac:parameter ac:name="name">System</ac:parameter>
                  <ac:parameter ac:name="separator">newline</ac:parameter>
                  <ac:parameter ac:name="atlassian-macro-output-type">INLINE</ac:parameter>
                  <ac:parameter ac:name="blankText">Not applicable</ac:parameter>
                  <ac:rich-text-body>
                    <ac:structured-macro ac:macro-id="88bca535-8899-4dd1-8422-64b6fbf4f9cb" ac:name="list-option" ac:schema-version="1">
                      <ac:parameter ac:name="label">Confluence</ac:parameter>
                      <ac:parameter ac:name="value">Confluence</ac:parameter>
                      <ac:rich-text-body>
                        <p>Confluence</p>
                      </ac:rich-text-body>
                    </ac:structured-macro>
                    <ac:structured-macro ac:macro-id="7336845d-e731-4285-b401-af27a49c4349" ac:name="list-option" ac:schema-version="1">
                      <ac:parameter ac:name="label">Jira</ac:parameter>
                      <ac:parameter ac:name="value">Jira</ac:parameter>
                      <ac:rich-text-body>
                        <p>Jira</p>
                      </ac:rich-text-body>
                    </ac:structured-macro>
                    <ac:structured-macro ac:macro-id="d37f855c-2287-42ee-b375-496eb237f6fc" ac:name="list-option" ac:schema-version="1">
                      <ac:parameter ac:name="label">Salesforce</ac:parameter>
                      <ac:parameter ac:name="value">Salesforce</ac:parameter>
                      <ac:rich-text-body>
                        <p>Salesforce</p>
                      </ac:rich-text-body>
                    </ac:structured-macro>
                  </ac:rich-text-body>
                </ac:structured-macro>
              </div>
            </td>
          </tr>
          <tr>
            <th colspan="1">Hosting platform</th>
            <td colspan="1">
              <div class="content-wrapper">
                <ac:structured-macro ac:macro-id="33e0d211-9666-402d-93d1-828c42676bdf" ac:name="list-data" ac:schema-version="1">
                  <ac:parameter ac:name="name">HostingPlatform</ac:parameter>
                  <ac:parameter ac:name="separator">newline</ac:parameter>
                  <ac:parameter ac:name="atlassian-macro-output-type">INLINE</ac:parameter>
                  <ac:parameter ac:name="blankText">Not applicable</ac:parameter>
                  <ac:rich-text-body>
                    <ac:structured-macro ac:macro-id="29854095-3f2b-4f60-9fb4-e2edd9804245" ac:name="list-option" ac:schema-version="1">
                      <ac:parameter ac:name="label">Server</ac:parameter>
                      <ac:parameter ac:name="value">Server</ac:parameter>
                      <ac:rich-text-body>
                        <p>Server</p>
                      </ac:rich-text-body>
                    </ac:structured-macro>
                    <ac:structured-macro ac:macro-id="0949eb91-b3d8-4b96-98c2-986b767f237b" ac:name="list-option" ac:schema-version="1">
                      <ac:parameter ac:name="label">Cloud</ac:parameter>
                      <ac:parameter ac:name="value">Cloud</ac:parameter>
                      <ac:rich-text-body>
                        <p>Cloud</p>
                      </ac:rich-text-body>
                    </ac:structured-macro>
                    <ac:structured-macro ac:macro-id="82406045-53fa-43a0-be08-7e2243215c08" ac:name="list-option" ac:schema-version="1">
                      <ac:parameter ac:name="label">Data Center</ac:parameter>
                      <ac:parameter ac:name="value">Data Center</ac:parameter>
                      <ac:rich-text-body>
                        <p>Data Center</p>
                      </ac:rich-text-body>
                    </ac:structured-macro>
                  </ac:rich-text-body>
                </ac:structured-macro>
              </div>
            </td>
          </tr>
          <tr>
            <th colspan="1">Add-on</th>
            <td colspan="1">
              <div class="content-wrapper">
                <ac:structured-macro ac:macro-id="65c25009-0410-4fe4-a43d-faea0a5fbaba" ac:name="list-data" ac:schema-version="1">
                  <ac:parameter ac:name="name">Addon</ac:parameter>
                  <ac:parameter ac:name="separator">newline</ac:parameter>
                  <ac:parameter ac:name="atlassian-macro-output-type">INLINE</ac:parameter>
                  <ac:parameter ac:name="blankText">Not applicable</ac:parameter>
                  <ac:rich-text-body>
                    <ac:structured-macro ac:macro-id="428934a0-d3b9-4f3d-857a-e54559e0b6ea" ac:name="list-option" ac:schema-version="1">
                      <ac:parameter ac:name="label">Reporting</ac:parameter>
                      <ac:parameter ac:name="value">Reporting</ac:parameter>
                      <ac:rich-text-body>
                        <p>Reporting</p>
                      </ac:rich-text-body>
                    </ac:structured-macro>
                    <ac:structured-macro ac:macro-id="51f24350-177c-4f3a-8679-6d7c15d496e1" ac:name="list-option" ac:schema-version="1">
                      <ac:parameter ac:name="label">Scaffolding</ac:parameter>
                      <ac:parameter ac:name="value">Scaffolding</ac:parameter>
                      <ac:rich-text-body>
                        <p>Scaffolding</p>
                      </ac:rich-text-body>
                    </ac:structured-macro>
                    <ac:structured-macro ac:macro-id="3aa691e6-7b4e-418e-8186-e675e90578aa" ac:name="list-option" ac:schema-version="1">
                      <ac:parameter ac:name="label">Connector for Salesforce and Jira</ac:parameter>
                      <ac:parameter ac:name="value">Connector for Salesforce and Jira</ac:parameter>
                      <ac:rich-text-body>
                        <p>Connector for Salesforce and Jira</p>
                      </ac:rich-text-body>
                    </ac:structured-macro>
                    <ac:structured-macro ac:macro-id="1e7f08ab-a102-48df-adae-b348af13abe0" ac:name="list-option" ac:schema-version="1">
                      <ac:parameter ac:name="label">Composition</ac:parameter>
                      <ac:parameter ac:name="value">Composition</ac:parameter>
                      <ac:rich-text-body>
                        <p>Composition</p>
                      </ac:rich-text-body>
                    </ac:structured-macro>
                  </ac:rich-text-body>
                </ac:structured-macro>
              </div>
            </td>
          </tr>
        </tbody>
      </table>
      <p>
        <br/>
      </p>
      <h1>Cause</h1>
      <ac:structured-macro ac:macro-id="c0fbf35f-7073-426d-87b9-b6f4502fb4c9" ac:name="hidden-data" ac:schema-version="1">
        <ac:parameter ac:name="whenNotEmpty">Cause</ac:parameter>
        <ac:parameter ac:name="atlassian-macro-output-type">INLINE</ac:parameter>
        <ac:rich-text-body>
          <p>
            <em>
              <span style="color: rgb(165,173,186);">Why did this happen? Describe the root cause of the problem in this</span> <a href="https://docs.servicerocket.com/scaffolding/macro-reference/text-data">Text Data</a> <span style="color: rgb(165,173,186);">macro.</span>
            </em>
          </p>
        </ac:rich-text-body>
      </ac:structured-macro>
      <ac:structured-macro ac:macro-id="4338715a-80cf-4273-9542-d838ddd68d39" ac:name="text-data" ac:schema-version="1">
        <ac:parameter ac:name="name">Cause</ac:parameter>
        <ac:parameter ac:name="atlassian-macro-output-type">INLINE</ac:parameter>
        <ac:rich-text-body>
          <p>
            <br/>
          </p>
        </ac:rich-text-body>
      </ac:structured-macro>
      <p>
        <span style="color: rgb(165,173,186);"> <em> <br/>
          </em> </span>
      </p>
      <h1>Solution</h1>
      <ac:structured-macro ac:macro-id="f73ddba9-b613-4ead-b2d4-89d47b18b9db" ac:name="hidden-data" ac:schema-version="1">
        <ac:parameter ac:name="whenNotEmpty">Solutions</ac:parameter>
        <ac:parameter ac:name="atlassian-macro-output-type">INLINE</ac:parameter>
        <ac:rich-text-body>
          <p>
            <span style="color: rgb(165,173,186);">
              <em>How do we fix it? Describe how someone would solve the problem in a concise, step-by-step guide in this <a href="https://docs.servicerocket.com/scaffolding/macro-reference/repeating-data">Repeating Data</a> macro.</em> </span>
          </p>
        </ac:rich-text-body>
      </ac:structured-macro>
      <ac:structured-macro ac:macro-id="28f3fbae-3e0d-4cfd-9a07-8970289c5088" ac:name="repeating-data" ac:schema-version="1">
        <ac:parameter ac:name="name">Solutions</ac:parameter>
        <ac:rich-text-body>
          <p>
            <br/>
          </p>
          <ul>
            <li>
              <ac:structured-macro ac:macro-id="35d7b36d-b4e8-497f-bd40-846bab1c9ba7" ac:name="text-data" ac:schema-version="1">
                <ac:parameter ac:name="name">Solution</ac:parameter>
                <ac:parameter ac:name="atlassian-macro-output-type">INLINE</ac:parameter>
                <ac:rich-text-body>
                  <p>
                    <br/>
                  </p>
                </ac:rich-text-body>
              </ac:structured-macro>
            </li>
          </ul>
        </ac:rich-text-body>
      </ac:structured-macro>
      <h1>Related articles</h1>
      <ac:structured-macro ac:macro-id="615877bd-9445-4c2a-bb1a-8af7576e61f6" ac:name="hidden-data" ac:schema-version="1">
        <ac:parameter ac:name="whenNotEmpty">RelatedArticles</ac:parameter>
        <ac:parameter ac:name="atlassian-macro-output-type">INLINE</ac:parameter>
        <ac:rich-text-body>
          <p>
            <span style="color: rgb(165,173,186);">
              <em>Conveniently search and link related articles through <a href="https://docs.servicerocket.com/display/SCAF/List+Data">List Data</a> macro.</em> </span>
          </p>
        </ac:rich-text-body>
      </ac:structured-macro>
      <ac:structured-macro ac:macro-id="e422450e-cdc0-447e-b243-8de975cb8e28" ac:name="list-data" ac:schema-version="1">
        <ac:parameter ac:name="multiple">true</ac:parameter>
        <ac:parameter ac:name="name">RelatedArticles</ac:parameter>
        <ac:parameter ac:name="type">auto complete</ac:parameter>
        <ac:parameter ac:name="separator">newline</ac:parameter>
        <ac:parameter ac:name="atlassian-macro-output-type">BLOCK</ac:parameter>
        <ac:rich-text-body>
          <ac:structured-macro ac:macro-id="e494cb79-a511-48fb-9317-a03b8754b721" ac:name="content-options" ac:schema-version="1">
            <ac:parameter ac:name="limit">40</ac:parameter>
            <ac:parameter ac:name="spaces">TEMPLATES</ac:parameter>
            <ac:rich-text-body>
              <p>
                <br/>
              </p>
            </ac:rich-text-body>
          </ac:structured-macro>
        </ac:rich-text-body>
      </ac:structured-macro>
      <p>
        <br/>
      </p>
      <p class="auto-cursor-target">
        <br/>
      </p>
    </ac:layout-cell>
    <ac:layout-cell>
      <p class="auto-cursor-target">
        <br/>
      </p>
      <p class="auto-cursor-target">
        <br/>
      </p>
    </ac:layout-cell>
  </ac:layout-section>
</ac:layout>