[Numpy-discussion] Google Season of Docs Ideas
> > NumPy serves many kinds of usersThe challenge: provide ways to guide > those users to the parts of the documentation most relevant to them. > I have a thought on how to approach this. We know many of the communities NumPy serves; let's next identify (for ourselves, not the proposal) what each of them needs. It could be as simple as: *Educator* - knows... - needs to know... *Researcher* - knows... - needs to know.. A table like that would be useful for self-assessment and planning. It helps answer questions like: - Which communities are we most shortchanging right now? - Which communities do we feel most strongly about (our largest base, most disadvantaged, etc.)? - If doc D is our next doc, does it help those communities? Or maybe we want to go round-robin through communities with each new doc. - What assumptions can a writer make about audience background? We're also then equipped to bring user categories out to a web page and meet the big-tent challenge head-on, with links like: - If you're an educator... - If you're a researcher... each one taking the user to an Educator, Researcher,..., page containing links to the information they're most likely to want. ___ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
[Numpy-discussion] Season of Docs technical writer
I look forward to participating in this year's Season of Docs. Though it's early, I'm eager to start a conversation; I've posted the webpage https://bennathanson.com/numpy2020 to share my thoughts on contributing. ___ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
[Numpy-discussion] Season of Docs technical writer
I've updated my page (https://bennathanson.com/numpy2020) to include a section on Curation and Adaptation. ___ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
[Numpy-discussion] GSoD 2020!
Congratulations on getting chosen once again for Season of Docs! I'm very eager to talk about collaborating. ___ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Numpy Documentation: How-to content
This sounds fantastic. In what context would the students be creating the notebooks -- as part of one of your existing ME courses, as a for-credit project, as a supervised but non-credit project? What were your thoughts on submission workflow? You review initially, then the student directly submits a PR? Suppose several students want to create a notebook on the same topic. Would you steer them to another topic, allow them to work independently and both submit (and we merge best of both), urge them to collaborate? Were you planning to keep the mechanical engineering context for these problems, or present abstractly? (I myself would like to see the application left intact. It doesn't obscure the steps, and I love the brothers-and-sisters-under-the-skin glimpse of how other domains make use of the same tools I do.) > easier to organize and...write I agree. Pedagogical soundness is also a plus. Procida says "what you ask the beginner to do [in a tutorial] must work" (https://documentation.divio.com/tutorials/). That means, among other things, that we need to specify a single environment to run the tutorial in. Notebook is the all-around win for this. ___ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
[Numpy-discussion] Guidelines for NumPy tutorials
I've submitted PR #11 in the new numpy-tutorials repo (https://github.com/numpy/numpy-tutorials/pull/11) to provide a checklist and standard style for writing tutorials. Added tutorial content is an objective of NEP 44. We're expecting part of the content to come from new contributors (for instance, through Ryan Cooper's generous offer to get his students involved, https://mail.python.org/pipermail/numpy-discussion/2020-May/080715.htmll). The PR will provide a guide for all contributors to work from. While "tutorial" is often used broadly for introductory material, here it is closely defined: a multistep participatory walkthrough for a user new to NumPy. This is the meaning of "tutorial" in NEP 44; it was originally distinguished from other kinds of documentation by Daniele Procida (https://documentation.divio.com/tutorials/). One goal of the PR, in fact, is to make sure the tutorial stays a tutorial and doesn't mission-creep into other kinds of introductory documentation. Procida's insight is that mission creep like this leads to failed docs. At today's docs meeting it was suggested that the PR be announced on the mailing list for possible further comment. ___ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
[Numpy-discussion] Google Summer of Docs Faq and Tutorial Proposed Structure .
Let me first say I'm a volunteer and not a member of the group that will evaluate proposals. But I can tell you how I would choose. A right-sized proposal is stronger than an overambitious one. I'd scale back and pick a single target. From your listed experience, this would be your first significant docs work. Before you can overhaul an entire site, you need to get a feel for the pace of the work. The review process alone guarantees the site can't be transformed in three months. For argument's sake, let's say you focus on mining the internet for how-to subjects. This is not a bad GSoD idea, because it's open-ended: No matter how fast you write, you'll never exhaust the supply of topics, and if work proceeds more slowly than you'd hoped, you will have established a methodology, and any how-tos we get are more than we have now. Apart from appropriate scope, a proposal needs credibility. GSoD tech writers are a coveted resource, so a project wants to be confident that the writer they pick will deliver the goods. We're scientists and engineers, yourself included, so we look for evidence. Put evidence in your proposal. Assuming you pick how-tos, show the NumPy team how thoroughly you've considered the issues, explain your methodology and its strengths and shortcomings, and, most importantly, give samples of how-tos you've transformed. It's like a job interview, but harder: Not only do you have to provide the answers, you have to anticipate the questions. Does that mean you have to do work upfront that you might do during GSoD? Yes. You're staking capital. The more you put on the table, the more confident the team can be in your sincerity and skill. That said, you do stand to lose it all if someone else is chosen. That can happen even if you send in a proposal that everyone agrees looks good. Your effort will not be a waste; you'll have developed skill in drafting a competitive proposal -- useful in grant writing, calls for papers, and next year's GSoD. Again, this is peer review, not official guidance. And to be clear, I myself am not participating in GSoD; I thought I might but chose instead to simply volunteer. ___ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Google Summer of Docs Faq and Tutorial Proposed Structure .
If you do choose how-tos, I meant to say that the first place to mine should be this very list. For instance, a question the other day on seeding random sequences sparked an illuminating and far-reaching discussion. Some things that make this list a great source: * Extracting how-tos from the mailing list does a real service -- questions on the mailing list are much less visible via Google search than SO questions * Answers here are likely to be deep and interesting (i.e., not simply answers you'll find in the docs) * We own the list; no doubts about usage rights * We have authoritative answers from code authors Mining only this list would not be enough for a proposal, however; there'd need to be something else as well (e.g., mining SO/Reddit). On the subject of mining SO, I'd suggest not only weighting by frequency but also searching out answers that came from the community -- e.g. Robert Kern, Warren Weckesser, Jaime Fernández del Río (jaime), and others whom I apologize for missing. Here again we'd add value by giving prominence (and an imprimatur) to the best answers. ___ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Add Chebyshev (cosine) transforms implemented via FFTs
> scipy.fft is a superset of numpy.fft, and the functionality included in NumPy > is really only the basics that are needed in many fields. Exactly this sentence might be useful on top of the FFT page. Is the right page reference/routines.fft.html? I can submit a PR. ___ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
