Jump to content

Documentation/Self-study guides

From mediawiki.org

This page explains how to write a self-study guide and is intended for anyone interested in writing this type of documentation.

The purpose of a self-study guide is to help readers learn a subject that's already covered in other documentation. A self-study guide explains what documentation to read, why, and in what order, to learn about the subject of the guide. It also provides context for what's often a set of distinct pages.

Writing a self-study guide means gathering links to materials from other locations, for example wikis and other websites, and then presenting a path to understanding complex concepts through these materials.

Note that a self-study guide should contain almost no new instructions. Instead, refer readers to existing materials and do not duplicate their content. If you realize that you need to write original material to explain an idea, place it in a separate how-to guide or a tutorial.

Note Note: See the examples at the end of this page to get an idea of how to use this template in practice.


Title: [Subject of the guide. Optionally include a "(self-study)" suffix]

== Prerequisites ==

Describe any requirements that the reader needs to meet to use the guide. This can include:
* familiarity with other concepts
* necessary software
* any required setup steps, accounts, or privileges

== [Section title (based on the idea described)] ==

Create separate sections to describe each bigger idea. Create sub-sections as necessary to break the idea apart.

In each section, include inline links to existing, relevant materials. Wrap these links in explanations that describe why a given page is relevant to the subject of the guide.

Add a Resources list with links to additional materials at the end of a section or subsection. These links should allow the reader to deepen or test their understanding of the section's idea.

Continue creating sections for other ideas until you have explained the subject of the guide.