[Top][All Lists]
[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
- Re: 1.6.0 release update., (continued)
- Re: 1.6.0 release update., Martin Grabmueller, 2001/05/03
- Re: 1.6.0 release update., Rob Browning, 2001/05/03
- Re: 1.6.0 release update., Martin Grabmueller, 2001/05/03
- Re: 1.6.0 release update., Lars J. Aas, 2001/05/03
- Re: 1.6.0 release update., thi, 2001/05/03
- Re: 1.6.0 release update., Rob Browning, 2001/05/03
- Re: 1.6.0 release update., Martin Grabmueller, 2001/05/04
- Re: 1.6.0 release update., thi, 2001/05/07
- Re: 1.6.0 release update., Martin Grabmueller, 2001/05/07
- Re: 1.6.0 release update., Neil Jerram, 2001/05/04
- Re: 1.6.0 release update.,
thi <=
Re: 1.6.0 release update., thi, 2001/05/03