Documentation/Conceptual overview template

Write a conceptual doc that helps users understand how a product or technology works, the major concepts they should know about it, and why they might (or might not) want to use it.

Examples

 * PAWS/About_Jupyter_notebooks_hosted_on_PAWS
 * wikitech:Help:Cloud_Services_introduction
 * 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.

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 pre-existing 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.

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?

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.

Diagram or graphics
Diagrams or illustrations can help readers understand key concepts quickly. Don't include detailed system architecture diagrams in overview or introductory documents. That level of information belongs in reference documentation, which readers use after they have built an understanding of the system in general.

Some good examples of conceptual diagrams:
 * mw:Parsoid
 * mw:Transclusion

Related documentation templates

 * Reference docs