On Tue, Dec 5, 2017 at 5:32 PM, Ralf Gommers <ralf.gommers@gmail.com> wrote:
On Wed, Dec 6, 2017 at 1:49 PM, Nathaniel Smith <njs@pobox.com> wrote:
- NEPs are really part of the development process, not an output for end-users -- they're certainly useful to have available as a reference, but if we're asking end-users to look at them on a regular basis then I think we've messed up and should improve our actual documentation :-) - NEPs have a different natural life-cycle than numpy itself. Right now, if I google "numpy neps", the first hit is the 1.13 version of the NEPs, and the third hit is someone else's copy of the 1.9 version of the NEPs. What you actually want in every case is the latest development version of the NEPs, and the idea of "numpy 1.13 NEPs" doesn't even make sense, because NEPs are not describing a specific numpy release.
The last two points are good arguments, I agree that they shouldn't serve as documentation. A separate repo has downsides though (discoverability etc.), we also keep our dev docs within the numpy repo and you can make exactly the same argument about those as about NEPs. So I'd still suggest keeping them where they are. Or otherwise move all development related docs.
Are these the dev docs you're thinking of? https://docs.scipy.org/doc/numpy-dev/dev/index.html Regarding discoverability, right now it looks like the only way to find the latest NEPs on google is by searching for something like "numpy-dev neps", which is pretty obscure. (It took me 4 tries to find something that worked. "numpy neps" seemed to work, but actually sent me to an out-of-date snapshot.) In Python, the PEP web pages are rebuilt on something like a 6 hour timer, and it's actually super annoying, because it means that when someone posts to the list like "hey, I just pushed a new version, tell me what you think", everyone goes and finds the old stale version, sometimes people start critiquing it, ... it's just confusing all around. So I do think we want to make sure there's some simple way to find them, and that it leads to the latest version, not a stale build or an old snapshot. Moving NEPs + development docs to their own dedicated repo would resolve this and seems like a plausible option to me. We could probably do better than we are now with the regular docs too. Though the experience with PEPs does make me a bit nervous about having versioned snapshots of the NEPs in all our old versioned manuals (which have tons of google-juice). -n -- Nathaniel J. Smith -- https://vorpus.org