shelve: writing out updates?!

[Robert Kern]

phil hunt wrote:

> Obviously it's good when stuff is well documented. 
> 
> I wonder if the barrier to good documentation is set too high?
> If i wanted to add some documentation here, I'd have to download the 
> current source for the latest Python documentation, download, 
> install and learn the code that processes the source documentation, 
> write my changes then send the results into the CVS. (I'm assuming 
> that's roughly correct -- I haven't actually done it).

No, write the content in a reasonable format (i.e. plain text), post it 
to the bug tracker, assign it to Fred Drake (I think), and he'll put it 
in the right format. If it's longer documentation, like for a full 
module, then it's better to actually learn the LaTeX so it can be 
dropped in as is.

> The point is, that would be a major effort, too major to merely add 
> a few lines detailing the .sync method.
> 
> But, what if the Python documentation was on a Wiki? Then it would 
> be easy to update! Of course, we would have to guard against false 
> or malicious updates, but Wikipedia manage that OK.

That's a debatable assertion, but I don't think we'll have the same 
problems of Wikipedia thanks to the apolitical nature of Python 
documentation.

> The 
> Documentation Wiki could then be used as a basis for the "official" 
> documentation that comes with each new release.
> 
> Does this idea make some sense? Or are there hidden pitfalls?

Yes! Someone actually has to do it! The same idea has come up time and 
time again. It's still not here because no one has been able to commit 
to the effort involved.

-- 
Robert Kern
rkern at ucsd.edu

"In the fields of hell where the grass grows high
  Are the graves of dreams allowed to die."
   -- Richard Harter