[pypy-dev] explicit documentation (re)organization

[holger krekel]

Hi Laura, 

[Laura Creighton Sat, Nov 06, 2004 at 02:01:53PM +0100]
> What you don't know is that that particular document was the one and only
> time I had ever managed to make ReST do <something>.  
> Or I thought up a neat way to express something, or I had to
> look up the spelling of a word.
> ...
> All in all, this means that the document continues to have present and lasting 
> value to me beyond its value to you -- or anybody else.

I don't think that the "pypy documentation for and from
developers" should primarily strive to have this side-function
of preserving bits and pieces of formatting or other meta-info
that might be helpful to particular users.

IMHO the pypy documentation serves two purposes: 

- letting the developers easily organize up-to-date
  documentation, by integrating hacking at ReST files
  into the coding process as seemless as possible

- letting others easily see this current view of the developers
  regarding the implementation and architecture of PyPy 

That being said i definitely see the point of wanting to
look at an earlier revision of a file, especially if it
has been deleted from the repo.  To date there is no nice 
tool i know off that provides you a complete search functionality
over ancestor revisions (not even trac at the moment although it 
goes some way). 

So we might move documents into some 'attic' instead of deleting them. 
But note that most often files will be modified and not deleted. 
And we certainly don't want to keep all older revisions of modified
files in some 'attic' folder as this would lead to a plethora of files
and would undermine the whole point of a version control system. 

Oh, and btw, if you say "i know that at EuroPython 2004 there was 
this nice ReST-thingie i did" you can issue 

    svn up -r "06-10-2004"

in the doc directory which gets you right back to the complete 
view at that time.  Taking this single-step indirection seems
reasonable enough to me for most cases. 

cheers, 

    holger