[pypy-dev] explicit documentation (re)organization

Laura Creighton lac at strakt.com
Sat Nov 6 12:19:04 CET 2004

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.


More information about the Pypy-dev mailing list