I would like all the documents produced to cotinue to be under svn source code control. 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.
This will be useful for new developers as well. If somebody suggests we do something which we once thought was a good idea but do no longer, it will be a lot easier to point them at the discussion that made us reject the idea rather than try to reconstruct it. When you reconstruct the idea, what you most often do is write 'why I would reject the idea now' believing that the reason you have now is the reason you had then, or a development of the one that you had then. This is often true. But sometimes the reason you have for adopting a new decision isn't actually a valid one, but the evidence for that shows up slowly. By the time you are all in agreement that the original reason you had for adopting this plan of action is not valid, you will have generated other reasons for having this plan of action -- including the old standby 'but we have a heck of a lot of code written with this plan in mind'. It often takes fresh eyes to see that the decision was the wrong one, and possibly it is time to yank out the code and start that bit over. We've already done this a bit -- have done plan a, and then decided to do it over as plan b, and then on the third think decide that plan a was better after all. This means we should be careful about saving old documentation, because what we toss out may come back later. Or something similar in a different shape -- they way we still have multi-methods now, but they don't do what they did a year and a half ago ... 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. 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. We will have to document in bits for the EU in any case. 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 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. Laura _______________________________________________ [EMAIL PROTECTED] http://codespeak.net/mailman/listinfo/pypy-dev
