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

[Brian Granger]

A few words on the documentation stuff:

* If docs are important - let's block the 4.0 release. Isn't that the
definition of "important" for software projects? Otherwise, everyone
will find other, more interesting things to work on (including me :-).
We don't have to block 4.0 on having *perfect* docs, but I think it
would be good to have a simple docs rubrics that all released packages
should pass before a release. As time goes on we can expand the rubric
and continue to improve the quality of docs. I have silently been
thinking this for a while...
* Our experience has shown that writing good docs is *extremely*
difficult - even more difficult than testing asynch JavaScript against
all browsers ;-) Because of this, I think the central docs effort
should be led by our most senior developers and writers. This doesn't
preclude community contributions, but I don't think that should be our
central docs strategy.

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...

Cheers,

Brian


On Tue, Jun 30, 2015 at 7:55 AM, Matthias Bussonnier
<bussonniermatthias at gmail.com> wrote:
>
> On Jun 29, 2015, at 05:44, Nicholas Bollweg <nick.bollweg at gmail.com> wrote:
>
> For why, see the Mathematica documentation, which is really a better
> yardstick than other open source projects.
>
> Yes we want to do that, though cross language and cross library is not easy.
> Mathematica has the advantage that they do not really distinguish
> the language from the sodlib.
>
>
> On Jun 29, 2015, at 06:59, Kyle Kelley <rgbkrk at gmail.com> wrote:
>
> Gosh, I'd rather read foo(path:string, notebookName:string) any day, instead
> of having to *also* reference aliases infer based on the name itself.
>
>
>
> Well you see what I mean, the types helps, of course naming arguments is
> necessary.
> But for a name like action_name_is_or_callback is not super nice.
> The types in typescript docs are also link so it’s easy to read, and you can
> get deeper
> details without looking at the source.
>
> --
> M
>
> (gosh, I was only in a plane for 11h, and got 180+  mails opening my laptop,
> so sorry if I skim through)
>
>
> _______________________________________________
> 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