Re: critical issues

[David Kastrup]

"Keith OHara" <address@hidden> writes:

> On Fri, 31 Dec 2010 16:31:23 -0800, Trevor Daniels
> <address@hidden> wrote:
>> ... the concern I had was this.  Quite a lot of the
>> documentation was written, not by inspecting the code
>> to see what was intended, but by experimenting and
>> writing up what was found.  I certainly worked that
>> way, and I think Mark and Keith did recently in
>> documenting the new spacing stuff.
>
> Pretty much.  If it makes you feel better, I did read a fair bit of
> the code to help build up a mental model of how things worked.

The problem is that one is documenting the implementation, not the
designed interface.  Which is fixating things at the wrong end of the
stick: the implementation should be free to gravitate towards its best
state without having to change the documentation and/or the interface.

-- 
David Kastrup