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. > >cheers, > > holger take care, Laura >_______________________________________________ >[EMAIL PROTECTED] >http://codespeak.net/mailman/listinfo/pypy-dev _______________________________________________ [EMAIL PROTECTED] http://codespeak.net/mailman/listinfo/pypy-dev
