DOC: How-to guide for how-tos

how_to_how_to.md

@@ -0,0 +1,69 @@
+# How to write a NumPy how-to
+
+How-tos get straight to the point. They either answer a focused question, or narrow down
+broad questions into a set of focused questions that the user can then choose among.
+
+## A stranger has asked for directions
+
+*"I need to fill my tank."*
+
+## Brief but explicit answer
+
+  * Three miles, take a right at Hayseed Road, it's on your left.
+
+Add useful details ("Hayseed Road", even though it's the only turnoff at three miles), but not irrelevant ones. Don't say "A lot of people have trouble finding fuel in this town." If you're on Route 3, don't also explain how to get there from Route 7. If there's interesting background (tutorial, explanation, reference, alternative approach), link to it so the user can discover it, but that information doesn't belong in a how-to.
+
+## Delegate
+
+  * Three miles, take a right at Hayseed Road, follow the signs.
+
+If the information is already in the docs, link to it -- don't repeat it. If the API doc is sufficiently clear, link directly to it after you've set the scene ("Three miles, take a right").
+
+## If the question is broad, narrow and redirect it
+
+ *"I want to see the sights"*
+
+The `See the sights` how-to should link to a set of narrower how-tos:
+
+  * Find historic buildings
+  * Find scenic lookouts
+  * Find the town center
+
+and these might in turn link to still narrower how-tos -- so the town center page
+might link to
+
+   * Find the court house
+   * Find city hall
+
+By organizing how-tos this way, you not only display the options for people who
+need to narrow their question, you also have provided answers for users
+who start with narrower questions ("I want to see historic buildings," "Which
+way to city hall?").
+
+## Examples come later
+
+Some how-tos cry out for an example. But examples go *after* the how-to information. Don't begin with a case study.
+
+## Not a tutorial
+
+How-tos can be long if there are many steps, but if each step requires an explanation,
+you're writing a tutorial rather than a how-to.
+
+## Subheadings for long how-tos
+
+If a how-to has many steps, include subheadings. They help by summarizing the significance of a step or group of steps and by helping readers find where they left off.
+
+## Why write how-tos when there's Stack Overflow, Reddit, Gitter...?
+
+ * We have authoritative answers.
+ * How-tos make the site friendlier to non-experts.
+ * How-tos bring people into the site and help them discover other information that's here .
+ * How-tos provide workarounds to the site's imperfect information architecture.
+
+## Why the firm distinction with tutorials?
+
+Distinguishing how-tos from tutorials (and explanations and references) is not pedantic. The division reflects readers' distinct needs and expectations. Readers with how-to requests should get exactly as much as they came for, in the form they expect to see -- regardless of how much more we'd love to share. Via links, we also give them access to that other information if they want it.
+
+## Is this page an example of a how-to?
+
+Yes -- until the "Why" headings. In a how-to, those would be links.