[IPython-dev] Proposal: soft moratorium on re-architecting for 5.0

[Brian Granger]

On Wed, Jul 1, 2015 at 11:02 AM, Fernando Perez <fperez.net at gmail.com> wrote:
> On Wed, Jul 1, 2015 at 12:33 AM, Brian Granger <ellisonbg at gmail.com> wrote:
>>
>> Would there be support for developing a simple docs rubric and
>> blocking 4.0 based on packages passing that rubric? SciPy could be a
>> great place for creating that rubric...
>
>
> I'm not very keen on this idea.  My impression is that we are very, very
> close to having 4.0 ready to go, and that at this point, putting a big block
> on the actual release would actually do much more harm than good, unless we
> can put a *very tight* time bound on it.
>
> My suggestion would be instead:
>
> - Let's open 5.x branches even now, for things where a few people are
> genuinely suffering from the blockage already (perhaps Matthias and Kester
> in certain areas, or Sylvain?).
>
> - Wrap up the 4.0 work as soon as possible, with the doc scaffolding we've
> been able to put in place.
>
> - As we start our 5.x cycle, we will make docs work a priority of our core
> team.  Once some of our hiring work is done, I may be able to find some
> cycles for this, and it's an area I would be delighted to put some thinking
> and effort towards.
>
> Or did you have a very constrained (time-wise) idea in mind?

That is why I proposed a rubric (or even a checklist) - it would allow
us to *begin* pushing on docs in a systematic way. We could constrain
the amount of time required by creating a checklist with more or less
detail and rigor. For example, here are some possibilities for such a
checklist:

* Every user focused package/repo should have a sphinx+RTD based documentation.
* Those package/repo docs should all be listed on the main docs
landing page at juypter.rtd.org.
* All notebook based documentation should be integrated into the
sphinx based documentation at a basic level - custom HTML in markdown
should be removed, images should be displayed using output rather than
in markdown and the notebooks should be listed in the appropriate
places in the sphinx toc. Notebooks should be *integrated*, not ghetto
dumped into sphinx.
* There should be no duplicate content in our docs.
* Content should be organized into logical, conceptual sections in a
way that users can find the documentation they want from our main docs
landing page in 2-4 clicks.

Even if the checklist/rubric is a target we are already almost
hitting, it would communicate a great message about the importance of
docs if we became willing to block releases on that checklist and
increase the rigor of the checklist/rubric over time.

I don't think that major rewrites of content before 4.0 is a good
idea, but I think there is a lot of simple docs organization changes
we can make that would improve users experience significantly while
not taking us too much time.

Cheers,

Brian


>
> Cheers
>
> f
>
> --
> Fernando Perez (@fperez_org; http://fperez.org)
> fperez.net-at-gmail: mailing lists only (I ignore this when swamped!)
> fernando.perez-at-berkeley: contact me here for any direct mail
>
> _______________________________________________
> IPython-dev mailing list
> IPython-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/ipython-dev
>



-- 
Brian E. Granger
Cal Poly State University, San Luis Obispo
@ellisonbg on Twitter and GitHub
bgranger at calpoly.edu and ellisonbg at gmail.com