[pypy-dev] explicit documentation (re)organization

[holger krekel]

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 source 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 development
> 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 fact
> that we have decided against a certain approach does not make it therefore
> uninteresting.  I'd like to be able to go back and think about roads not
> taken at some point.  

Yes, I see the point.  However, when we delete things in a certain revision
they don't go away from the repository.   It is always possible to look at 
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 ...

> ... 
> While organising the documentation is likely to help, I think that the reason
> the py lib documentation is better than the pypy documentation is because
> Holger sat down one weekend and wrote a lot of it.

Actually even some more than just a weekend. 

> I don't see the same sort of commitment to writing
> documentation for the pypy project because more of the pypy
> code is 'experimental -- subject to change'.  The people who
> know the most about the code -- those who are writing it --
> don't want to document something they might want to rewrite
> next week, and so it goes, because it is actually hard to
> find a good time to document the code that was done which is
> one reason why the WP approach may be good for us.  

Well, the py lib is not documented completly either.  I think
it makes most sense to document the most stable parts 
(which we partly already did but it's not organized well
enough IMO).  For futuristic stuff it may also be good 
to write down the ideas and mark them as "futuristic, 
subject to change".  

> We will have to document in bits for the EU in any case.

Yes, although i see the "documentation for developers" 
somewhat independent of reporting to the EU especially
since the EU hasn't even confirmed yet. 

> But the ongoing problem remains.  Would you rather document the stuff that we
> already have, that might change, or write the changes?  I think we are going to
> always feel a push towards writing the code.
> 
> Perhaps a way for us to turn discussion we had on the mailing lists into
> lists of things for newcomers to read would be more effective?  This is only
> an idea.  I am not sure of that.

I do think that instead of writing long mails spending the time
to write a "future" chapter is often a good idea. 
 
> I am going to be away travelling, first to Brussels and then to the USA until
> Vilnius, and so I cannot help with documentation much until Vilnius.  Then
> I could help a lot, provided that there is enough I understand that needs
> documenting.  When I run out of things I understand, you will have to teach
> me stuff -- which might not be what you want to do, and you would prefer hacking.

Btw, Laura&Jacob, please list your arrival/departure dates and accomodation status at 

    http://codespeak.net/moin/pypy/moin.cgi/VilniusSprintAttendants

cheers, 

    holger