Ideas for NumPy: Season of Docs 2020

I hope to participate in Season of Docs (samples, bio) and am thrilled to find NumPy again among the organizations seeking help. I’m amazed, as you surely are, by NumPy’s importance. [1]

Though it’s early, I’m eager to start a conversation. I have a number of thoughts about contributing.

The fourfold way

Search for advice on losing weight, saving money, or writing documentation, and everyone always has the same few things to say. Daniele Procida changed the game with his insight on separation of concerns [2]. I’m happy that you plan to put those insights to use.

Potential new pages

  • A “NumPy Traps and Pitfalls” page would be widely read [3].
  • “Not your father’s NumPy”: Stack Overflow sometimes gives dated information, and even frequent users may still do things the hard way. We’d have a page summarizing old techniques that have better replacements.
  • “Get the most out of NumPy”: In a similar spirit, there must be NumPy features we wish people would use more, or features like broadcasting whose value isn’t obvious. This is a page of before-and-afters.
  • “When not to use NumPy”: Alternative tools may fit better. Adding NumPy may hurt performance. This page would instruct users when to turn elsewhere.

Unwelcome welcoming committee

Newcomers to the site are met by five identically dressed strangers each offering to show them the town:

Here, less is more. I would be happy to improve new-visitor experience by consolidating some pages and renaming others.

Views and copies

For the wave of incoming technical writers, Season of Docs is foreign language immersion.

Though I’m also an engineer, this is true for me, too. There are two upsides in it:

  • I see learning NumPy not as a hurdle to surmount but as a reward in itself: the journey is the destination.
  • As an engineer, I have a foundation to build on.

I’ve done editing; I would dig right into reorganizing the site or weaving in external text. But I do also love to write, and I’ve come here to learn. NEP 44 lists missing pages that require some domain knowledge, so they’re not in the Season of Docs proposal. I have an idea – it might be too ambitious – sparked by Irio Musskopf’s list in #15793 of what a Copies vs Views page should contain. For a topic in NEP 44, I’d work from a list like Irio’s of what topics need to be covered. I’d research it for a fixed period and write it up for review. Even if I can’t do a topic full justice, having the work started can move it a long way.

At the top of this note I link to writing samples, but I’d like to show you also how I’d write for NumPy. This is a possibly not-quite-accurate start to a Views and Copies page. And this, though you’re not in the market for a NumPy beginner’s introduction, is how I’d introduce NumPy. [4]

Curation and adaptation

When news breaks, reporters fan out – to the scene, to the press conference, to call on neighbors and relatives. The story you read is the work of an editor who’s drawn their accounts together. I’ve been that editor: I can pull together the course notes showing how-to and the book chapter that gives perspective and the terrific quote from somebody’s blog.

I’ve also been the editor who cuts and revises colleagues’ writing but still has to work with them. That draws partly on tact, partly on a built-in tradeoff (if you want to appear here, this is the process), and partly on displaying convincing results.

Big-tent issues

As the Season of Docs proposal points out, NumPy documentation has a big-tent problem: It has many kinds of users and each wants a different subset of docs. I’ve thought about defining client classes strategically, somewhat in the spirit of Software Carpentry’s learner profiles. I could help in the effort to set priorities – on whatever basis we choose – for selecting documentation efforts [5]. Similarly, I can help organize the site so each community gets what it needs.

Believing the Internet

Season of Docs cites the benefit of outsider perspective. Stack Overflow has it in quantity. To discover what perplexes NumPy users most, I downloaded SO’s 73,450 NumPy questions and sorted them by number of views. [6] For at least the top few, I’ll investigate whether the answer could have been found in the docs. The list might also be a resource for anticipating troubleshooting questions. This doesn’t qualify as a project; I mention it as what a restaurateur would call an amuse-bouche. [7]

Search fails us

I see SciPy survey respondents have already spoken up on this, so I’ve moved this section to another page.

Graphical site map

When I see an outline of page headings I keep thinking of data plots: If numbers can be brought to life in an image, maybe doc trees can too. Can a foldable, clickable tree help users navigate? Is it useful internally for reorganizing the site? On what doc scale is it useful, if at all? I’d like to find out, and again it’s just amuse-bouchery. (After writing this, I see SciPy is already looking into it.)

Thank you

I appreciate your reading this note. I hope we can collaborate this Season.


[1]Even if NumPy were a two-developer project in Egyptology, you had me at hello. I very much liked the thoughtfulness of your project ideas page.
[2]He’s no help on dieting or getting rich, unfortunately.
[3]Title taken from Andrew Koenig’s 160-page C Traps and Pitfalls. I’m guessing NumPy has fewer skeletons.
[4]Artist conception. It may not resemble your software.
[5]I realize that in open source you sometimes just need to take what’s offered.
[6]Page views increment so often that SO searches won’t sort on them and the API doesn’t include them, so this was a screen-scrape.