Documentation/Patterns/How-to guide
Write a how-to guide that describes how to approach a real-world problem. Ensure that headings identify key stages, or important things that must be taken into account. Test examples for accuracy.
Examples[edit]
Description[edit]
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.[1] 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[edit]
Introduction[edit]
The first section under the title introduces the topic and audience of the page.
Section headings[edit]
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[edit]
Commands and examples should be tested for accuracy.
Recommended[edit]
"How to..." title[edit]
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".