Explanation or Discussion articles explain background information and provide context-specific knowledge on a particular topic. The goals of an explanation article is to help readers understanding, not to teach concepts or provide steps in a task.
Explanation articles work well when they:
- Give context to a subject or topic that your readers might not have
- Explain the background about a topic that might not be evident in Reference or How To articles
- Suggest alternative approaches or different ways of thinking about a use case or technical problem.
- Help readers make connections between related concepts, and form a better understanding of the subject.
Summarize what the reader will achieve by reading the explanation article.
- Are you writing for developers or for managers?
- Are you writing for people who have a certain problem to solve?
- Are you writing for a particular industry or market segment?
If you plan on using terms that might not be familiar to your readers, list them all in this section. Declaring them here lets you use any abbreviated forms of the terminology you're using in the body of the explanation.
Think about structuring explanation topics like you would for a presentation to a group who don't know anything about your chosen subject. Your explanation should introduce ideas gradually, so your audience can grow their understanding of the concepts it covers.
It can be easy to blend explanations with other types of content, like How To or Reference articles. Some tips to avoid mixing documentation types:
- Avoid instructions, procedures, or any content that doesn't focus solely on building upon the conceptual understanding of the explanation topic.
- If you find yourself writing steps or describing how to do something in detail in your explanation article, you need to shift your focus away from describing the tasks, and go back to the concept. Remind yourself of the main goals of your article.
Here are some clues that your explanation article is not staying on-topic.
| Clue | Solution |
|---|---|
| You write steps to achieve something that you're describing in your topic. | Look for opportunities to link to other topics that complement your explanation content. Link to these articles in-line or at the end of the document in the "Where to next" section. |
| You want to insert a tutorial video directly into the article. | Link to the video in the "Where to next" section instead, so your audience doesn't get distracted by the video. |
| You include YAML and JSON structures of end-points. | You are mixing too much reference content into your explanation article. Bring the focus back to understanding the structures, not documenting everything you can do with them. If your explanation article still needs to link back to the API, you can add the link with a brief explanation to the Related Articles section. |
-
Example 1.
-
Example 2.