guile-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: 1.6.0 release update.


From: thi
Subject: Re: 1.6.0 release update.
Date: Mon, 7 May 2001 00:47:40 -0700

   From: Neil Jerram <address@hidden>
   Date: 04 May 2001 23:27:06 +0100

   I'm all for striving, but I think it would be quite wrong to delay a
   release until the documentation is `complete'.  We are as likely to
   achieve perfect documentation as we are to achieve perfect code.

agreed.  i used the wrong word, unfortunately.  i should have said: what
strikes me as bad practice is to to lose parity between code quality and
documentation quality.  for any given piece of code (whether perfect or
not), the documentation should "match" it in some sense.  the situation
of having code (of any quality) but no documentation at all is basically
very out of whack, except for 0.x releases [he says, remembering lack of
docs in ttn-pers-scheme ;-].

   Also note that, the better the documentation gets, the more readers
   are motivated to provide patches for small errors in it.  But readers
   in general can't do that if the documentation hasn't been released!
   So the overall process is accelerated by releasing the documentation
   even when not yet complete, I think.

yes.

   I'm afraid I'm not currently maintaining a doc task list.  Martin's
   list is quite useful, but (as Martin also said) you can find things
   to investigate simply by grepping for FIXME.  More generally, there
   is still so much to do that tasks can be easily be identified just by
   reading and reviewing the manual; with the current balance of
   finished vs. not finished, I think that the burden of maintaining a
   complete to do list would be more of a hindrance than a help.

   On the other hand, I have a feeling that an `anti-todo' list might be
   quite helpful (for both maintenance and readers); i.e. a list of the
   parts of the manual that have been reviewed and are considered to be
   finished.

well, the classic solution to this management issue is to combine the
TODO and DONE lists and use some convenient notation to distinguish
status.  i notice that devel/tasks.text has not been updated since
2000-12-22 -- maybe we can use that file also for documentation tasks.

thi



reply via email to

[Prev in Thread] Current Thread [Next in Thread]