[IPython-dev] Wiki chaos...

Wed Jul 10 13:03:39 EDT 2013

On Wed, Jul 10, 2013 at 11:16 AM, Brian Granger <ellisonbg at gmail.com> wrote:

> Aaron,
>
> On Wed, Jul 10, 2013 at 7:41 AM, Aaron Meurer <asmeurer at gmail.com> wrote:
> > Embrace the chaos.
> >
> > You don't use naming conventions for your branches in git. That's because
> > branches are cheap and throwaway, and it would be a waste of time to
> > organize them. Wikis are the same way.
>
> Our wiki pages are not throwaway.  Our *official* development
> resources are there:
>

Do you allow throwaway wiki pages? For SymPy, we encourage people to dump
interesting things on the wiki.

There are also official things there too, like development guidelines and
gsoc reports. But I guess our workflow is not as officialized as yours (we
don't have peps or anything).

>
> * IPEPs
> * Our official github workflow, description of how we use issues,
> coding style guide, etc.
> * Our roadmap
>
> All of this is highly curates and written by/maintained core
> developers.  Some of the content is less curated (our Cookbook).
>
> > Take a look at the SymPy wiki pages
> > https://github.com/sympy/sympy/wiki/_pages. The only official naming
> > convention we have is for GSoC pages. We use the wiki for throwaway
> tests,
> > developer guides, user written pages about uses of SymPy, little bits of
> > "documentation" that don't belong in our docs like comparisons to other
> > computer algebra systems, and prototypes and write ups for new features.
>
> Most of the active parts of our wiki are not user written.  They are
> written by core devs.  Our choice was to put all of our development
> information on GitHub rather than Sphinx - to keep it all in the same
> place.
>
> > Our organization comes from a listing of the important pages on the main
> > page. That only accounts for about half the wiki pages. For the rest,
> there
> > is the list of all pages, which is what I usually use. If you want a
> search,
> > clone the git and use git grep.
>
> That is exactly (in part) what I have done - we have separate index
> pages for different categories.
>
> > You probably won't embrace the chaos, so my recommendation is to create
> an
> > index page (or just use the main page) and organize the pages by there
> by a
> > list of links under headers. That's much less painful than page naming
> > conventions.
>
> We have already done that....:)
>

So why do you need prefixes?

Aaron Meurer

>
> Cheers,
>
> Brian
>
> > Aaron Meurer
> >
> > Sent from my iPad
> >
> > On Jul 10, 2013, at 12:47 AM, Fernando Perez <fperez.net at gmail.com>
> wrote:
> >
> > One problem with prefixing all pages is that those prefixes, if I
> > understand how GH wikis work correctly, have to be part of the visible
> > page title.  Which for some pages makes for pretty horrible names.
> > For example the gallery title is perfectly fine as
> >
> > A gallery of interesting IPython Notebooks
> >
> > but it would look pretty ugly if called
> >
> > Cookbook: A gallery of interesting IPython Notebooks
> >
> > or similar, IMO.
> >
> > Since there's no actual auto-indexing machinery or other organizing
> > mechanism that these pseudo-namespace prefixes provide, I'm also not
> > convinced that it makes sense to mandate their use rigidly everywhere.
> > For certain categories I think they do make sense, like say cookbook
> > recipes or sprints lists. But I think we're inevitably bound to have
> > 'miscellaneous' pages that don't neatly fit in any single label.  And
> > creating a  zillion prefixes just so everything can have its own
> > prefix doesn't seem to be such a good idea either.
> >
> > In summary, I think the problem is that wikis are inherently prone to
> > some of this slightly chaotic growth, which is why I've never liked
> > them too much.  I think they fill a useful role when used in a pretty
> > *limited* fashion, partly so that they can be manually tended to.  But
> > for larger-scale efforts, without a massive metadata machinery and an
> > army of people like what Wikipedia uses, it's kind of hopeless. For
> > wikipedia, pages have very rich categorical/tagging tools that the
> > entire wiki system understands, mines, and uses to offer management
> > and navigation.  We don't have that at GH, just a plain wiki in its
> > barest form.
> >
> > Sorry to be a bit of a downer, but I'm just not convinced that more
> > prefixing is really going to really solve anything beyond a thin
> > cosmetic veneer issue.
> >
> > Cheers,
> >
> > f
> >
> > ps - I'm pretty sure, BTW, that I'm the guilty party in having created
> > the lab meetings page without a prefix, sorry :)  Part of it is
> > probably that I find it so ugly to read those titles that I
> > unconsciously just ignored the idea... Feel free to change it if you
> > really think it will help.
> >
> > On Tue, Jul 9, 2013 at 5:07 PM, Brian Granger <ellisonbg at gmail.com>
> wrote:
> >
> > Hi,
> >
> >
> > A while back I spend a couple of days organizing the IPython GitHub
> >
> > wiki.  I know this will probably seem anal, but I think it is
> >
> > important that we use a logical structure for each of our pages and
> >
> > the wiki as a whole.  To induce this structure on the flat GitHub wiki
> >
> > namespace, we are naming our wiki pages with a prefix such as "Dev :"
> >
> > or "Cookbook: " or "Install: ".  This structure is also present in our
> >
> > sub-indices - we have a separate index page for each of these
> >
> > categories.  When someone created the wiki page for the lab meetings,
> >
> > it was created at the top level, rather than under the "Dev: "
> >
> > category and put in the top level index rather than the "Dev: " index.
> >
> > I could fix this myself in a few minutes, but I don't want to become
> >
> > the "police" for our wiki organization.  Instead, I would like
> >
> > everyone to help keep the wiki organized.  Can someone clean this up?
> >
> > If we don't want to use this structure, but instead keep things
> >
> > organized another way, I am completely open to that.  I just want the
> >
> > wiki organization to decay into chaos like it did before...
> >
> >
> > Cheers,
> >
> >
> > Brian
> >
> >
> > --
> >
> > Brian E. Granger
> >
> > Cal Poly State University, San Luis Obispo
> >
> > bgranger at calpoly.edu and ellisonbg at gmail.com
> >
> > _______________________________________________
> >
> > IPython-dev mailing list
> >
> > IPython-dev at scipy.org
> >
> > http://mail.scipy.org/mailman/listinfo/ipython-dev
> >
> >
> >
> >
> > --
> > 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
> >
> >
> > _______________________________________________
> > 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
> bgranger at calpoly.edu and ellisonbg at gmail.com
> _______________________________________________
> IPython-dev mailing list
> IPython-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/ipython-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/ipython-dev/attachments/20130710/7a68df5f/attachment.html>