Solution Article Guidance

Overview

A good Solution article is an article that is structured to inform, instruct, or direct a specific audience down a logical path to matching an issue with a solution and having the confidence to independently apply the solution without needing to raise a support ticket.

Ready to create a Solution article? Here’s some guidance to get you started:

  • Know your audience
  • Do your Research
  • Design a meaningful structure or format

Know your audience

Knowing your audience when writing a Solution article provides essential insights into what supporting details, data, and structure will be necessary for the reader to understand the message you are trying to deliver.

Do your Research

Doing research when writing a Solution article helps you gain a deeper understanding of the problem and root cause behind the proposed solution, improving how you translate the problem from the user’s perspective.

Work with Subject-Matter Expert(s) (SMEs):
Before writing Solutions, you must understand them. SMEs hold the keys to understanding. This interaction also helps you understand the needs of your audience.

Design a meaningful structure or format

The structure of an effective Solution article primarily includes the following sections to guide the reader through a logical path of matching a problem with a solution:

See the Community Blog Guidance article for further details on the following sections.

Title

A title should be a headline that demands attention and should have keyword combinations containing the exact error messages, product, and version that reflects the issue to help quickly find the information in search results.

Overview (Introduction)

Start by giving a concise and vivid description of the problem (from the user’s perspective), the context, and the solution (s) the article will cover. Again, this tells the reader they’re in the right place and you’re knowledgeable about the problem they want to solve.

Symptoms

This section illustrates the issue’s symptoms (behavior, error codes, location, and debugging details) and how the problem impacts end-users vs. the expected behavior.

Provide a clear and concise problem description from the user’s perspective.
Illustrate the exact error messages, where and when the defect is seen (e.g., terminal, browser, path/to/log). Provide steps to reproduce the symptoms and errors.

Technical descriptions sometimes draw on the “five senses” and analogies, allowing ALL skill levels to conceptualize the problem. Use a combination of visuals and text to both “show” and “tell” the reader about the use case details being conveyed.

Include log snippets and error messages in the format of the appropriate terminal font, inline code, code block, or screenshots with proper captioning to highlight the defect. Consistent and appropriate use of bold, italic, and code style for text elements improves readability and helps avoid misunderstandings.

Example format:

Recent Changes

(What changes, if any, trigger the issue) Describe what recently changed that introduced the problem being experienced.

Cause(s)

Describe the origin and primary Cause of the problem. What happened, why it happened, and how to verify this. Root Cause Analysis (RCA) assumes that systems and events are interrelated. An action in one area (recent change) triggers an action in another, and so on.

The Cause must be a clear and concise, detailed technical explanation translated into layperson’s terms. Hence, ALL skill levels must understand the specific actions contributing to the problem.

Understanding these actions allows the reader to trace back and correlate where the problem started and how it grew into the symptom(s) they’re now facing.

Solution

This section gives technical requirements with step-by-step instructions to solve the issue.

Use short, concise steps equivalent to one or two actions to resolve the issue. (E.g., Choose Add Users from the Actions menu). Illustrate commands and expected responses.

If applicable, solve the problem using the UI and command line equivalent, enabling ALL skill capabilities to apply the solution.

Example UI/CLI :

Links to Relevant Resources

Links to relevant Jira’s/Issue Trackers, documentation, companion articles, and websites.

Again, don’t make the reader Google “how to…” dig through documentation or raise a support ticket - Always provide a direct link to any resource that helps your reader gain additional knowledge that also serves as supporting evidence.

Following these steps should set you up for writing great Solution articles! :woman_technologist:

1 Like

Another format that I find useful is the Problem Statement. This is typically more of a high level presentation, usually based on some Root Cause Analysis. I find it particularly useful in addressing architecture and design problems, where we want to propose an architectural or design improvement.

1 Like