Framing possible contributions

[cooperrc]

In PR #11, @bjnath, @melissawm, and @cooperrc discussed two topics

1. Having a template for the tutorials in this repo
2. Framing the possible contributions into each document style.

Topic 1 is covered by PR #11 so I wanted to bring up topic 2 in a separate issue.

My thoughts on framing the contributions would be to provide a checklist (maybe it could be included in the PR for a tutorial or how-to). I am using a scientific document as a template because I think many users are using NumPy in scientific applications. Scientific documentation also provides a nice structure to present a problem, propose a solution, and show evidence that it works while providing room for future work.

The checklist would also serve to help review and organize the content. Here is a proposed checklist for review (and general feedback):

Introduction

• Who is the audience
• What will you learn
• What is the problem
• What will you do

Methods

• What do you need
• What will you use
• Are the steps of solution are detailed enough for user
  # Results

# Discussion

Wrapping up

• Are there any missing pieces or future work?
• How did NumPy help solve the original problem posed?

# Conclusion

[melissawm]

Hi, @cooperrc . I like the checklist, and I was wondering if we could use these questions/answers to guide the contributor towards the content type they should write, e.g. Tutorial or How-to. Do you think this is useful/possible?

Example: if I answer those questions with, say

• I'm writing for an advanced user
• What they will learn is best practices when using advanced indexing, instead of solving a specific problem
• I'd like to use a more narrative style

This sounds like a Tutorial.

[cooperrc]

@melissawm that makes sense to me. It seems like we're building a nice definition for our tutorials here. The more I think about it, the more this checklist fits in tutorial space rather than how-to space.

[bjnath]

@melissawm -- I couldn't decide what doc type your three bullets added up to, and then I realized: There is no solution -- the problem is overconstrained.

Use case determines the writing style, and the second bullet makes it a how-to. It's not possible to chose a quadrant and a writing style independently; it's precisely the purpose of the quadrants to lay down the style.

[bjnath]

@cooperrc: For reporting scientific results, IMRaD -- Introduction, Methods, Results, and Discussion -- is valuable standard practice.

That doesn't make it useful everywhere for all kinds of information. It doesn't make it good for weather reports, or broadcasting a ballgame, or software documentation.

We can't decide whether IMRaD is a tutorial or how-to because it's neither. Scientific papers don't have quadrants; they live in exactly one space and are best written in that one format.

IMRaD can do only what it's meant for. It has some of the same concerns as software documentation, but it is not software documentation.

The checklist asks some of the same questions a doc writer should be asked, but it's not a doc checklist, it's an IMRaD checklist, and it will lead to good papers but not good documentation.

Supplying NumPy with student contributions is an inspired and generous offer; again, thank you. Submissions in IMRaD style, though, will require heavy editing, and it's not guidance we should offer to contributors outside the classroom.

[cooperrc]

Supplying NumPy with student contributions is an inspired and generous offer; again, thank you. Submissions in IMRaD style, though, will require heavy editing, and it's not guidance we should offer to contributors outside the classroom.

@bjnath, I'm all for revising the style to fit into the NumPy documentation better. This format is something that works for me when I'm creating tutorials in other software for courses, but I'm sure my students would love if I get some more experience in writing these docs. It may help to reframe the Results&Discussion in a more Documentation vocabulary.

One thing I have been researching and dealing with these past couple of years is how to design an experience that leads to the learner gaining knowledge, as opposed to memorizing facts. One thing that I'm discovering is that there should be a journey for the learner. The learner identifies a need or missing information (Intro), then checks the tools and resources they need (Methods). The learner then goes through trials and experimentation (Results or How-to in Absolute Beginner). The learner then achieves something, but the missing piece in some tutorials is some kind of reflection or synthesis with the learner's previous knowledge and experience.

I think this last step of reflection (if we call it discussion, conclusion, or wrap-up), is a key piece for completing the tutorial learning journey. How about an Intro, Methods, Wrap-up as edited?

[melissawm]

@cooperrc I agree your checklist goes more in the direction of tutorials. I also agree that a standard scientific report format is not ideal for this repository, but I think we can find a way to organize this.

For the checklist: in my view, "what the reader will learn" and "what the reader will do" should be thought-about together for a tutorial; the main reason for doing anything should be to teach something. My view is that you decide first on what to concept or idea to teach - and then think of a problem/solution that will lead you there. In this case, I think I would order the Intro and Methods items differently, and make sure the "What you'll learn" and "Who is this document for" are the most important questions in the checklist. I also think the wrap-up could be simplified, but it's a good idea to keep comments about what was not covered and what could have been done differently if this were a real-world problem.

[bjnath]

@cooperrc Thanks for your comments. I have two thoughts:

1. The students are learning through writing; the users are learning through reading. Techniques to maximize a writer's learning won't necessarily maximize a reader's.

2. Knowledge scopes are different. Student writers must go beyond facts to mastery. For tutorial readers, facts often suffice, or even just impressions. Readers of Melissa's tutorial may not develop deep knowledge of singular value decomposition, but they get a feeling for NumPy and how it's applied.

[cooperrc]

I moved "What will you learn" to the Intro check 2 and cleaned up the final wrap-up.

For the checklist: in my view, "what the reader will learn" and "what the reader will do" should be thought-about together for a tutorial; the main reason for doing anything should be to teach something. My view is that you decide first on what to concept or idea to teach - and then think of a problem/solution that will lead you there. In this case, I think I would order the Intro and Methods items differently, and make sure the "What you'll learn" and "Who is this document for" are the most important questions in the checklist. I also think the wrap-up could be simplified, but it's a good idea to keep comments about what was not covered and what could have been done differently if this were a real-world problem.

@melissawm, that's a good idea to reorder the list and reduce/combine items, but keep What you'll learn and Who is this for as important questions for the tutorial.

1. The students are learning through writing; the users are learning through reading. Techniques to maximize a writer's learning won't necessarily maximize a reader's.
2. Knowledge scopes are different. Student writers must go beyond facts to mastery. For tutorial readers, facts often suffice, or even just impressions. Readers of Melissa's tutorial may not develop deep knowledge of singular value decomposition, but they get a feeling for NumPy and how it's applied.

@bjnath, these are excellent points: reading and learning != writing and learning. One of the big benefits I see here is that writers (in my case students) will develop a much deeper knowledge of a subject by communicating to a reader. I'm trying to build experiential education as proposed by Dewey's Democracy and Education. The cornerstone of Dewey's ideas is that education is a continual process that involves community and communication.