Documentation/Patterns/How-to guide

Guide an already-competent user through a real-world situation, to complete a task correctly or solve a problem. Ensure that headings identify key stages in the work to be done, or important things that must be taken into account. Test examples for accuracy.

Review a landing page on Phabricator

See the checklist

Examples

• mw:Gerrit/Tutorial
• mw:Phabricator/Help

Description

How-to guides are directions that take the reader through the work required to solve a real-world problem. How-to guides are goal-oriented. There is not always a simple linear path through a problem or to a goal, and a how-to guide is often more than a series of orderly steps.

A how-to guide should assume basic competence and familiarity on the part of the reader. Its role is to be a co-pilot rather than a teacher.

Required

Introduction

The first section under the title introduces the topic and audience of the page.

Section headings

Sections should be organized by task, as far as possible. Headings should use verb phrases where appropriate, but can also highlight things that must be considered as part of the work (e.g. "Security implications").

Working examples

Commands and examples should be tested for accuracy.

Recommended

"How to..." title

The title of the page can usually start with "How to...". However it can be more elegant sometimes to use other forms, such as "Troubleshooting xxx" or "Yyy checklist".