DOC: Template/checklist for uniform NumPy tutorial style

[bjnath]

Jupyter notebook serving as a template and tutorial for writing NumPy tutorials.

In common speech "tutorial" can mean several kinds of introductory material, but here it's meant in the narrow sense of Daniele Procida's guidelines. Thus the notebook is not meant to give general rules for introductory material, only for narrowly defined "tutorial" documentation.

[review-notebook-app]

Check out this pull request on 

Review Jupyter notebook visual diffs & provide feedback on notebooks.

---

Powered by ReviewNB

[cooperrc]

Hi @bjnath, I had some ideas for the tutorial (how-to) format as well. I was laying out some ideas as a technical/scientific document. What do you think about these:

Learn to write a Numpy tutorial # Title:

Give a descriptive title that tells readers what to expect

e.g. How to solve a linear set of equations in Numpy

Who is the audience:

Tell the reader who you expect to be reading the how-to

e.g. This is meant for engineers and scientists that want to use Numpy to solve a set of
linear equations.

What is the problem:

Define the vocabulary, background information, and the specific problem you're solving

e.g. Linear equations are typically straigthforward to define in engineering and
scientific applications, but general solution methods can be difficult to do by hand.
Numpy has a great set of tools to quickly solve linear sets of equations.

What you'll do:

Give a brief overview of the approach you are documenting

e.g. You'll use numpy arrays and the numpy.linalg functions to solve a set of linear
equations

What you'll learn:

Give a brief overview of what skills will be taught or strengthened

e.g. You'll learn to set up linear equations, define them as arrays, and get a solution
that satisfies the equations

What you'll need Method of solution

Here you detail the process of the solution. What objects and functions are used to define
and then solve the problem?

e.g. In this how-to I define a set of linear equations as 2D and 1D arrays to define the
coefficients and outputs for a given set of equations. Then, I use the numpy.linalg.solve
function to solve for the unknown variables in my equations.

Results:

Here you walk the reader through the step-by-step process of problem definition, code
setup, and solution.

e.g. import the libraries, define variables, solve the problem, get the solution

Discussion:

• How do the results from numpy relate to the problem?
• How does it solve the initial problem?
• Are there any missing pieces or future work? Compare the result to other methods
  or results

Conclusion:

Here you describe how these skills made the problem easier to solve, or faster, or better.

e.g. using numpy to solve linear equations in engineering and science is a way to speed up
calculations for lots of interdependent linear systems

[bjnath]

This has many good ideas! Your teaching experience shows.

A question we haven't tackled is whether these student contributions are tutorials or how-tos.  This isn't a pedantic distinction. Their goals diverge enough to require separate styles.

My understanding is that these are tutorials -- they're guided tours with explanations. 

1. Thus the title becomes "Solve a linear set of equations in NumPy" rather than "How to solve a linear set of equations in Numpy."

2. What's the contribution of the "Who is the audience" section? What would happen if it were omitted?

3. How about making "What is the problem?" simply "The problem"?

4. We want to avoid having so many headings that they stop being road signs and start being a bill of materials. I'd suggest putting "Method of solution" and "Results" under a single standard heading for each tutorial's main content. (I confess I don't know yet what the heading should be.) The introduction would be what's currently under "Method of solution", with each tutorial step under a subheading. Perhaps we can find less academic-sounding wording than "Method of solution" and "Results."

5. Did you mean the "Discussion" section to pose those questions or answer them? I like challenges, but we should provide all the answers, with the usual "try it yourself before checking the answer." Our readers are depending on the tutorial and have no access to TAs or office hours to learn if their answers are correct.

6. The goal of "What you'll need" is to ensure the reader has prerequisite libraries installed, datasets downloaded, etc., before beginning the tutorial.

7. Though a "What you've learned" (or "Conclusions") section is valuable in teaching, I'm not sure it's needed in this context. A course covers many points and needs summarizing way stations to keep them in front of students. Here we've covered one topic that the reader has already bought into.

8. Small suggestions: a) colons are unnecessary in the headings; b) uppercase P in NumPy.

[bjnath]

Rereading your comments, I realized I misunderstood why the proposed structure reflected an academic paper -- you want students to be prepared to write in that style. I apologize for missing this and have no wish to interfere.

Documentation writing is a valuable skill as well. But I think it's fine if students write to an academic-paper goal and we edit the content into more of a documentation style.

[cooperrc]

Hi @bjnath, thanks for reviewing the suggestions!

This has many good ideas! Your teaching experience shows.

A question we haven't tackled is whether these student contributions are tutorials or how-tos.  This isn't a pedantic distinction. Their goals diverge enough to require separate styles.

My understanding is that these are tutorials -- they're guided tours with explanations. 

I agree that these should be fit into tutorials or how-to's. I lean towards a more how-to-style because the pedagogical bar is a little lower. The writer can detail steps to achieve a goal for other people that may be familiar with Python or Numpy or other pieces of the guide without having to build small steps for new users to get comfortable.

1. Thus the title becomes "Solve a linear set of equations in NumPy" rather than "How to solve a linear set of equations in Numpy."

If these are tutorials, then they should definitely be reframed. Maybe even "Learning linear algebra solutions in Numpy" or "The basics of linear solutions in Numpy"

2. What's the contribution of the "Who is the audience" section? What would happen if it were omitted?

This section (I think these could be more of a check-box response e.g.

• Who is the audience:
• What is the problem:
• ... )

This would be very important to help us organize the tutorials (beginner/intermediate/advanced) and it would help the writer explain to a target audience during writing.

3. How about making "What is the problem?" simply "The problem"?

Makes sense to me, thanks.

4. We want to avoid having so many headings that they stop being road signs and start being a bill of materials. I'd suggest putting "Method of solution" and "Results" under a single standard heading for each tutorial's main content. (I confess I don't know yet what the heading should be.) The introduction would be what's currently under "Method of solution", with each tutorial step under a subheading. Perhaps we can find less academic-sounding wording than "Method of solution" and "Results."

Maybe we could combine headings and have a list of questions that should be answered in each one:

Introduction

Who is this for, what is the problem, what will you do

Methods

What you'll need, What will you learn, what will you use

Results

List detailed steps of solution with brief explanations

Discussion

Conclusion

5. Did you mean the "Discussion" section to pose those questions or answer them? I like challenges, but we should provide all the answers, with the usual "try it yourself before checking the answer." Our readers are depending on the tutorial and have no access to TAs or office hours to learn if their answers are correct.

The discussion (in my mind) should answer the questions posed. So, for the linear equation example. We have x=np.linalg.solve(A,b) and x is our answer. What are the units of x? Which values did we care about when we originally framed the problem?

For a circuit, we may be solving for the voltage drop across a set of resistors. So the units would be ohms and maybe we care about the total voltage drop from x[-1] to x[0] so deltaV = x[-1]-x[0] ohms.

6. The goal of "What you'll need" is to ensure the reader has prerequisite libraries installed, datasets downloaded, etc., before beginning the tutorial.

I like that. It should definitely be in the Methods area of the document

7. Though a "What you've learned" (or "Conclusions") section is valuable in teaching, I'm not sure it's needed in this context. A course covers many points and needs summarizing way stations to keep them in front of students. Here we've covered one topic that the reader has already bought into.

I like the conclusion (even if its just a sentence) to wrap up the long document and bring the reader back to where they started:

see problem -> build plan -> get solution -> return to beginning with new knowledge

Sometimes I just read an intro-conc on documents to see if the problem and applications are really what I'm looking for.

8. Small suggestions: a) colons are unnecessary in the headings; b) uppercase P in NumPy.it

Thanks! Missed that typo.

[cooperrc]

Rereading your comments, I realized I misunderstood why the proposed structure reflected an academic paper -- you want students to be prepared to write in that style. I apologize for missing this and have no wish to interfere.

Documentation writing is a valuable skill as well. But I think it's fine if students write to an academic-paper goal and we edit the content into more of a documentation style.

Hi @bjnath, I do want students to practice writing, but I think they would still get a lot out of writing documentation-style documents or academic-style. I'm presenting some formats that work for me and that I usually have students follow. It would be great to tweak them if it reaches a broader audience or it becomes more clear.

[bjnath]

Thanks for this good discussion. Some thoughts:

a target audience

Defining the target audience is essential, I agree, and easy to forget. But rather than using terms like intermediate, let's make it operational: "This assumes basic familiarity with linear algebra" -- the kind of concreteness used in listing course prerequisites.

This information then goes in the "What you'll need" section (aka "Prerequisites") along with the physical prerequisites like installed libraries.

organize the tutorials (beginner/intermediate/advanced)

I resist opaque labels like "beginner, intermediate, advanced" for several reasons.

1. Users expect to see articles in a easy-to-advanced gradient. They already expect that the last will be harder than the first. Labels add no information, but in addition...
2. "Beginner, intermediate, advanced" are poorly defined (compared to explicit prerequisites, as mentioned above).
3. They never will be well-defined, because difficulty is multidimensional. NumPy beginners can be linear algebra experts and NumPy experts can be linear algebra beginners.
4. Because "beginner, intermediate, advanced" seem like concrete categories but aren't, writing to one of these categories is the opposite of defining an audience and leads to trouble, like our "absolute basics for beginners" guide. Not only is "beginner" never defined, anything you might imagine "beginner" to mean is contradicted.
5. Not only is it impossible to set up these partitions in a multidimensional continuum, they're unnecessary. Unlike enrolling in a course, it costs nothing to glance over an article and decide whether the level is appropriate, just as we do in life. Readers already know that earlier articles will be easier than later ones. We invite them to find their own level and read what interests them. It's harmless to punch above your weight; you may learn something from an advanced article even if you couldn't pass an exam in it.

All that said, since we do want to organize the pieces easy-to-hard in some approximate ordering, I'm fine with an internal tag to help us know whether a piece is intended for the first, middle, or last third.

If these are tutorials

Let's calibrate. How would you characterize https://github.com/bjnath/numpy_ipynb/blob/master/tutorial-svd_gh.ipynb -- how-to (How to do singular value decomposition on an image) or tutorial (where SVD is a pretext to experiment with the linalg library)?

There's been discussion on the mailing list of how to seed random sequences, with a follow-up on how to seed multiple parallel sequences. The defining how-to question is "I want to know about this, and nothing that's not connected with reaching this goal." A linear equation how-to would be "How to solve a system of linear equations using X technique."

"The basics of linear solutions in Numpy"

Content written to this title might fall in Procida's explanation quadrant. That said, I should take another look at his samples to beef up my intuition. Insisting on the categories may seem like hairsplitting but I think he's brilliantly insightful that conflating them leads to failed documents.

[melissawm]

This is an excellent discussion. I really like how this is shaping up.

A few suggestions:

• I think the audience information is extremely useful for the writer, but not necessarily for the reader. I think in that sense keeping it in the template is nice as a question to the writer, so they can best focus their efforts. And I also strongly agree that the "Beginner, Intermediate, Expert" framing is incomplete and so I usually suggest something along the lines of the Carpentries Learner Profiles idea, where you would build one or more personas that would find this material useful. I find this very helpful when writing, both to help me figure out the tone of the content as well as the scope of the material. This makes the documents harder to organize, though, which is why in another issue I considered the use of labels for this. Labels are less linear and more fluid, and I think makes it easier for people to find what they're looking for. Unfortunately I still haven't figured out the best technical framework for this.

• This discussion has evolved into two different ones:

  1. Having a template for the tutorials in this repo
  2. Framing the possible contributions (by @cooperrc's students or anyone else, really) into each document style.
     I think these are separate discussions. I propose we focus here on a general template for tutorials. This is not to say the discussion should be stopped, rather that the PR can be merged and maybe we can continue this discussion in another issue specifically addressing this problem.

What do you think?

Thanks for all your effort and energy!

[cooperrc]

Thanks @melissawm and @bjnath,

1. Having a template for the tutorials in this repo
2. Framing the possible contributions (by @cooperrc's students or anyone else, really) into each document style.
   I think these are separate discussions. I propose we focus here on a general template for tutorials. This is not to say the discussion should be stopped, rather that the PR can be merged and maybe we can continue this discussion in another issue specifically addressing this problem.

What do you think?

I agree, the initial merge will be an excellent addition to the repo. It will be great to have the template included. Do you mind if I open a separate issue to discuss "2. Framing possible contributions"?

[bjnath]

Monday's doc meeting is approaching and we can wrap it up there -- @cooperrc, will you be joining?

[cooperrc]

Monday's doc meeting is approaching and we can wrap it up there -- @cooperrc, will you be joining?

I'll be there 👍

[melissawm]

Thanks @melissawm and @bjnath,

1. Having a template for the tutorials in this repo
2. Framing the possible contributions (by @cooperrc's students or anyone else, really) into each document style.
   I think these are separate discussions. I propose we focus here on a general template for tutorials. This is not to say the discussion should be stopped, rather that the PR can be merged and maybe we can continue this discussion in another issue specifically addressing this problem.

What do you think?

I agree, the initial merge will be an excellent addition to the repo. It will be great to have the template included. Do you mind if I open a separate issue to discuss "2. Framing possible contributions"?

Not at all!

[melissawm]

@bjnath the only remaining issue I'd like to check before merging is whether you think it would be useful to leave a bullet prompting the writer to think about who the learner is; I've always found it extremely useful when writing educational content. I believe empathy goes a long way to help guide the writer to choose what needs to be explained. I would also add something about the scope/length of the document. For example, the Absolute Beginners Tutorial is very long, and I would hope we got more concise documents with a more contained scope in this repo.

[bjnath]

a bullet prompting the writer to think about who the learner is

I agree. It has as much significance as choosing a quadrant.

something about the scope/length...Absolute Beginners Tutorial is very long

The tutorial format automatically restricts length: the subject is "Do X", and when X is done so is the tutorial. The reason Absolute Basics is long is that it isn't a tutorial. It has no goal, so it goes on until the writer decides to stop. We've learned a lot about doc structure since the time that was written.

[melissawm]

Looks good to me! Maybe @rgommers wants to take a look?

[rgommers]

LGTM too. I just read it once, it all makes sense to me. I didn't read all the review comments - seems everyone is happy, but just in case there's still discussion ongoing I'll leave it to @melissawm to merge this.