[pypy-dev] explicit documentation (re)organization

Laura Creighton lac at strakt.com
Sun Nov 7 13:30:25 CET 2004

In a message of Sun, 07 Nov 2004 12:03:19 +0100, holger krekel writes:
>Hi Laura, 
>I don't think that the "pypy documentation for and from
>developers" should primarily strive to have this side-function
>of preserving bits and pieces of formatting or other meta-info
>that might be helpful to particular users.
>IMHO the pypy documentation serves two purposes: 
>- letting the developers easily organize up-to-date
>  documentation, by integrating hacking at ReST files
>  into the coding process as seemless as possible

We share this goal.

>- 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.

This changes, of course, when you are writing an 'Introductory Manual for
New Users' or some such, where the explicit goal of the work is to
communicate with new users.  I am not opposed to the writing of such things,
but I don't see it as having much to do with the ongoing documentation of
a project, except coincidentally.

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.  There is nothing wrong with this.  Efforts to keep
what we wrote in sync with what we actually are doing, in my experience have
always resulted in people documenting less and less and less. I don't want
the responsibility of keeping what I wrote current with what we are doing.
If I am stuck with this, I will document to the minimum extent possible.  

>That being said i definitely see the point of wanting to
>look at an earlier revision of a file, especially if it
>has been deleted from the repo.  To date there is no nice 
>tool i know off that provides you a complete search functionality
>over ancestor revisions (not even trac at the moment although it 
>goes some way). 

Now you know why I wanted to write a CAPS system at Strakt. :-)  Some day
real soon now, it will even do this properly.

>So we might move documents into some 'attic' instead of deleting them. 
>But note that most often files will be modified and not deleted. 
>And we certainly don't want to keep all older revisions of modified
>files in some 'attic' folder as this would lead to a plethora of files
>and would undermine the whole point of a version control system. 

Yes.  Outlining the cases when you want to undermine the whole point of
a version control system is precisely what I am trying to do.  When documents
change a lot over their lifetime, there is often a case to be made for having
different versions of the document (mar 2000, oct 2000, dec 2001) and the
like available, as reference documents.  Deciding which documents deserve
such treatment is an art, more than a science.

Without such a history, you end up presenting your current ideas without the
context of how they evolved to what they are at present.  In some cases, this
'dis-in-history'-ing is the actual goal, and what you are trying to do.  But
in other cases, it is the historical development of the roadmap, that is of
interest, not wherever the arrow 'We are Here' currently points.  They are
contradictory goals, and extremely hard to realise at the same time.

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.  Then we finish hacking that,
and move on to other goals and make other documents. Time passes.  The
code that the original doc referred to gets refactored and modified in
the light of new ideas we have in the context of our new goals.  The
original doc does not get touched, because it is no longer interesting
in the context of where development is happening now, or next week, or
next month.  Eventually somebody decides that the document is so
obsolete that they delete it.

>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.  

Also, I don't know about you, but when you remember a phrase from a
book or a webpage, don't you remember stuff like

'about 2/3rds of the way through the book, on a right-facing page, second
 to last sentence before a new paragraph' ?

People who remember information independently of their presentation medium
have different searching and retreival needs than those who remember their
information with lots of embedded context.  It's a neat hard problem in
cognative science and human-computer interfaces.

>    holger

take care,

>pypy-dev at codespeak.net

More information about the Pypy-dev mailing list