[IPython-user] Manual vs. Wiki

Ville M. Vainio vivainio at gmail.com
Tue Dec 12 12:12:41 CST 2006


On 12/12/06, Fernando Perez <fperez.net at gmail.com> wrote:

> Could you put this info in the actual manual?  There's a real danger
> we're going to start having an outdated manual where new features are
> documented somewhere on the wiki and old ones in the html/pdf manual,
> with no clear way for users to know where to look for stuff.
>
> I'm open to discussing how to best handle this, but I think we should
> try to use the wiki for what it  does best (collaborative,
> community-maintained information and frequently evolving things), but
> I still believe in the value of a solid, well-organized manual.

There's a huge effort difference in maintaining the wiki manual and
the current official manual, with all the lyx stuff etc. I typed out
what is currently in the wiki page while waiting for stuff to compile
/ start / unzip / whatever at work - w/ only the official manual,
there wouldn't be any text at all; and I believe we are much more
likely to receive external contributions (examples, notes etc.) to the
wiki page. The concept of a monolithic manual is a bit outdated these
days, IMHO. When I want to know how to do something, I google it, and
I don't think I ever looked at the official manual for information
after playing with ipython for the first time.

I'm not at all against solidifying the information into a static
manual, but we should let the information become complete through the
wiki. After that, we can see how to transcribe it to the manual.

The official manual should probably have a note about the recommended
way to do things and how to find information about it, though.

I don't see an obvious solution to this problem - I recall there were
a series of flamewars on python-dev about this as well a while ago.

-- 
Ville M. Vainio - vivainio.googlepages.com
blog=360.yahoo.com/villevainio - g[mail | talk]='vivainio'


More information about the IPython-user mailing list