[pypy-dev] explicit documentation (re)organization

holger krekel hpk at trillke.net
Sun Nov 7 14:03:15 CET 2004


[Laura Creighton Sun, Nov 07, 2004 at 01:30:25PM +0100]
> In a message of Sun, 07 Nov 2004 12:03:19 +0100, holger krekel writes:
> >- letting others easily see this current view of the developers
> >  regarding the implementation and architecture of PyPy 
> 
> But we don't share this one.  I want us to write documentation primarily
> for us.  I think that there can be a place for 'documentation for
> others, and introductory material' but that is not, primarily, what I
> am interested in doing when I am writing documentation.  I write documentation
> first for me, and then for the people I work with, and last and by far
> the least for other interested parties.

In an open source context this distinction is a fluid thing.  If we
want more people to understand PyPy and contribute i don't see much
value in trying to come up with strict distinctions. 

> The ongoing documentation that we write for ourselves is constantly becoming
> obsolete as what we are doing differs from what we thought we would do when
> we wrote something.

I hope we can evolve into a model where we document things that
are pretty stable.  For example, the interpreter <-> object space 
interaction hasn't changed much since 2002 (!).  But i would argue
that with today's organization you wouldn't easily get to all the
documentation describing it. At least this can be improved by 
putting aways with all the links that are just distracting. 

> ... 
> What actually happens, wehn documenting, in my experience, is that
> somebody writes a document, and it gets modidied quite a bit while it
> is the focus of some work that is being hacked on right now, or will
> be hacked on in the immediate future.

Honestly, i don't see this happening with most of the projects
i am involved with. A positive example is the core CPython
documentation development, probably. It certainly doesn't happen
much with PyPy so far.  

> >Oh, and btw, if you say "i know that at EuroPython 2004 there was 
> >this nice ReST-thingie i did" you can issue 
> >
> >    svn up -r "06-10-2004"
> >
> >in the doc directory which gets you right back to the complete 
> >view at that time.  Taking this single-step indirection seems
> >reasonable enough to me for most cases. 
> 
> Not for me.  I am not looking for something to read, but something to
> scan and to search.  Which means I want it as a webpage I can glance
> at, and that Google can index.  

Maybe, but this is getting quickly out of scope of my current effort. 
Also, if you make all versions accessible to google how do you
think google will order what it finds?  Especially mentioning 
google makes IMHO a good case for offering only up-to-date documentation 
on the web because otherwise people will get at all the outdated 
information too easily. 

Hum, i guess i should just postpone changing anything about
the documentation right now.  I have enough to do before the
Vilnius Sprint, anyway.

cheers, 

    holger



More information about the Pypy-dev mailing list