[pypy-dev] explicit documentation (re)organization

[Laura Creighton]

In a message of Sat, 06 Nov 2004 12:34:31 +0100, holger krekel writes:
>Hi Laura, 
>
>[Laura Creighton Sat, Nov 06, 2004 at 12:19:04PM +0100]
>> I would like all the documents produced to cotinue to be under svn sour
>ce code
>> control.  
>
>sure, using subversion for holding the basic documentation is certainly 
>not going to go away :-) 
>
>> And I really do not want obsolete things deleted, only moved.  At
>> some point, one of us is likely to want to do a paper on the developmen
>t
>> process, and it will be very useful to have things that document what
>> we used to think, and when we thought it for that purpose.  Also, the f
>act
>> that we have decided against a certain approach does not make it theref
>ore
>> uninteresting.  I'd like to be able to go back and think about roads no
>t
>> taken at some point.  
>
>Yes, I see the point.  However, when we delete things in a certain revisi
>on
>they don't go away from the repository.   It is always possible to look a
>t 
>former revisions and see what happened. I completly agree that this 
>is something we want to have.  Also Jum and me are working on the 
>new codespeak setup which will feature a "trac" environment which
>allows to search for older commits and files ...

The trac sounds interesting.   Requiring that I look things up on the
repository might be ok for documents that are current, but have
changes in them, but I think is inappropriate for entire documents
that are obsolete.  We've run into this problem before.  I've written
something, and it becomes obsolete.  Somewhere along the line, in an
effort to not confuse people with old stuff, you take the what seems
reasonable step of removing this.

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.

But I don't notice that it is gone until the next time I need something
from it, and then I expect to be able to find it by clicking on something.
So what I would prefer is a quasi-mirror of the pypy site, with a header
of 'obsolete'.  If it isn't in the current, then I can find old docs in the
same location as they would be if they were still current.  I need to be
able to do 'click-click-click -- aha, there is the table I was looking for --'
and then get on with what I want.

<snip>

Laura

ps - updated the page, and bonus hero points for working over one weekend.