Documentation/Conceptual overview template

A conceptual overview helps explains a topic through explanation, providing background and context.

Examples

• wikitech:PAWS/About_Jupyter_notebooks_hosted_on_PAWS
• wikitech:Portal:Toolforge/About_Toolforge
• wikitech:Help:Cloud_Services_introduction
• mw:New_Developers/Introduction_to_the_Wikimedia_Technical_Ecosystem

Description

A conceptual overview clarifies, deepens and broadens the reader’s understanding of a subject. These types of pages are explanation-oriented; they help users acquire knowledge and skill. Conceptual introductions cover the core concepts a user should know to help them effectively proceed to use a product, system, or technology. For complex topics, these pages may focus more on orienting the reader to the larger conceptual landscape, and helping them understand the differences between many available options. Whether they are introductory or advanced, conceptual overviews help the reader build a mental model and learn fundamental concepts.

Page contents

Required

Descriptive title

The title should capture the name of the product, technology, or system it describes. It should indicate that it is an introduction or overview to that topic. Consider using titles like "Introduction to ____", "How _____ works", or "Overview of ______".

Topic introduction

In a few sentences, describe:

• Which product, technology, system, or topic does this page provide an overview for?
• What will the reader understand after they read the page?
• Who is the intended audience? Is there assumed prior knowledge they should have to be able to read this page?

Example:

This page provides an overview of Wikimedia software and infrastructure for new technical contributors. Its goal is to help developers understand the major areas where you can apply your technical skills to help support and grow the Movement.

Table of contents

Include a table of contents so the reader can use the page structure and headings to skim, assess, and navigate the page.

What is X

Create an excerpt or use partial transclusion to reuse content from this section in other pages, like the product/technology/topic landing page.

Why X matters

Provide context: why does this thing exist? What use cases does it exist to serve? Why would anyone need or want to use it? For broad topics: why should the reader care about this? What will it serve them to acquire this knowledge?

How X fits in with Y

Is there a bigger picture worth explaining here? Only include historical information if it actually impacts the user experience today. Don't overload the reader with historical minutiae just because you think it's interesting.

Constraints and alternatives

Are there reasons to not use the product/technology? What should the prospective user be aware of before they spend more time trying to use or learn about this topic? What are the known limitations of the product/technology? What other alternatives should they consider? What constraints, rules, or requirements should they know about in advance?

Key concepts

What systems or background information does the user need to understand, even if only at a high level, before they can effectively use this product or technology? For example, a conceptual overview about data dumps could cover concepts like the types of content in the dumps, and how the dumps are formatted, so that the user understands what they encounter when they start working with the dumps.

Get started

Link to a setup or quick start guide, and/or to tutorials or hands-on learning tools. If this is a very high-level introduction that covers concepts at a higher level than specific products or technologies, link back to the cross-collection landing page for the general topic.

Recommended

Diagram or graphics

Diagrams or illustrations can help readers understand key concepts quickly. Include them only if they're at the appropriate level of detail -- don't include full system architecture diagrams in overview or introductory documents. That level of information belongs in reference documentation.

Some good examples of conceptual diagrams:

• mw:Parsoid
• mw:Transclusion

Content templates

template	mediawiki.org	Meta-Wiki	Wikitech
mw:Template:Excerpt	Available	Not available	Not available
mw:Template:Last updated	Available
mw:Template:Note	Available

Related documentation templates

• Reference docs