[IPython-dev] Wiki chaos...

[Aaron Meurer]

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.

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.

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.

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.

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/ipython-dev/attachments/20130710/345a8bf5/attachment.html>