Overview: What Should Go Into an Article?

Deciding what to include in an article depends on the type of information needed to answer a specific question. Articles should be tailored to either provide foundational understanding or actionable instructions, but not both at once. The scope and level of detail in an article should match the reader's needs and the purpose of the article.

• Articles should be focused on either concepts or procedures, not both.
• Linking to related resources can help readers find additional context or detail.

Key Terms

Scope: The breadth of the topic covered in an article. High-scope articles address broad questions, while low-scope articles focus on specific tasks.
Detail: The depth of information provided. High-detail articles give step-by-step instructions; low-detail articles provide overviews.
Foundational Article: An article that explains concepts, context, or vocabulary, without procedural steps.
Actionable Article: An article that provides detailed instructions for completing a specific task.

• Scope and detail are inversely related: broad scope means less detail, narrow scope means more detail.
• Foundational articles help readers understand concepts; actionable articles help them perform tasks.

Background: Foundational vs. Actionable Articles

Foundational articles are designed to explain concepts, provide context, and define key terms. They avoid step-by-step instructions and instead focus on giving readers a big-picture understanding. Actionable articles, on the other hand, are focused on guiding readers through specific procedures with detailed steps and, when appropriate, screenshots.

• Foundational articles answer "what" and "why" questions.
• Actionable articles answer "how" questions.
• Each article should have a clear and limited scope.

Why Scope and Detail Matter

Matching the scope and detail of an article to its purpose makes it easier for readers to find the information they need. Trying to cover too much in one article can make it difficult to write and harder for readers to understand. Keeping articles focused and linking to related resources helps maintain clarity.

• Focused articles are easier to write and understand.
• Linking to other resources provides additional context without overloading the article.
• Clear separation between foundational and actionable content improves usability.