[pypy-dev] explicit documentation (re)organization

holger krekel hpk at trillke.net
Sat Nov 6 11:33:16 CET 2004


hi folks, 

i may not be alone in thinking that the current documentation
organization in PyPy leaves an lot to be desired.  IMO the
main problem: we don't have a clear and maintained entry point
for documentation for developers (tm) and we don't cleanly
link all the _relevant_ and somewhat up-to-date documentation. 
Also we link to a lot of half-way/not decent/wrong documentation. 

So i plan to move towards i model that is already used 
with the upcoming py lib (http://codespeak.net/py ): 

- there would be a directory which holds an "index.txt" 
  which will be ResT-translated in order to serve 
  as the main developer documentation entry point 

- this index.txt will link to the various important 
  other documentation chapters _explicitely_

- linking to the chapters happens with relative links
  so that you can rest-convert and check links before
  checking in.  With the py lib there even is a test 
  that checks that the documentation does not produce warnings. 
  
Currently, in PyPy we are using an implicit scheme which
basically rest-converts everything that was dropped into some
directories.  IMO the result is confusing, unordered and
didn't really work out. 

I believe that getting the documentation in a  better shape is
crucial to involve new developers (and even the current ones :-) 

Comments?  

I'd like to do the reorganization over the weekend and would
afterwards appreciate any help in bringing the documentation
up to date, especially deleting or moving all the obsolete
stuff. This is real work but it really makes a difference 
so please help ... 

cheers, 

    holger



More information about the Pypy-dev mailing list