Troubleshooting articles allows perfect document solutions for commonly encountered problems. A straight-forward, concise article can quickly guide customers to fast problem resolution.
Use Scaffolding's live template to create a consistent format for your troubleshooting articles to increase effectiveness and ease of use. This template can help you to structure the basic requirements -- such as defining the problem, including the affected environments, stating the cause, explaining the solution, and 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.