From d1c28ed6c609e4acf6e64ec22bdd8711d4860246 Mon Sep 17 00:00:00 2001 From: Ben Nathanson Date: Sat, 25 Jul 2020 11:47:15 -0400 Subject: [PATCH 1/2] DOC: How-to guide for how-tos Writing guidelines for how-to docs. --- how_to_how_to.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 how_to_how_to.md diff --git a/how_to_how_to.md b/how_to_how_to.md new file mode 100644 index 00000000..9c9ef2b6 --- /dev/null +++ b/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 given the prefatory information ("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. \ No newline at end of file From 166920578d5591b08f27190011a54f86f21d4e24 Mon Sep 17 00:00:00 2001 From: Ben Nathanson Date: Thu, 3 Sep 2020 10:50:09 -0400 Subject: [PATCH 2/2] DOC: Replace uncommon word in how-to instructions Replaced the word "prefatory" with a simpler paraphrase. --- how_to_how_to.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/how_to_how_to.md b/how_to_how_to.md index 9c9ef2b6..0552e9c6 100644 --- a/how_to_how_to.md +++ b/how_to_how_to.md @@ -17,7 +17,7 @@ Add useful details ("Hayseed Road", even though it's the only turnoff at three m * 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 given the prefatory information ("Three miles, take a right"). +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 @@ -66,4 +66,4 @@ Distinguishing how-tos from tutorials (and explanations and references) is not p ## Is this page an example of a how-to? -Yes -- until the "Why" headings. In a how-to, those would be links. \ No newline at end of file +Yes -- until the "Why" headings. In a how-to, those would be links.