Re: [GLISS] - alternative viewpoint

[David Kastrup]

James <address@hidden> writes:

> But I believe unless we now do something that is backward-incompatible
> with a (yet) undocumented function in the Notation or Learning manuals
> that we don't hold back the patch for the code, it would be nice to
> have it all documented as well, but that isn't always the case.
>
> The later footnote syntax was a case in point (I think) where we did
> change the syntax significantly enough that the old documentation
> would have been incorrect as opposed to incomplete/missing, we
> couldn't really push that on the users until had had been documented.

Well, it is unrealistic to expect both code and documentation to be
created entirely linearly, without the need of iterations.

In fact, sometimes it is while documenting things that it becomes clear
that an interface was chosen ill-advisedly.  And then it sometimes makes
sense to restart the interface design.

I think it was during the documentation of the footnote stuff that we
came up with several examples (including use of s1*0/<>) that made clear
that we were better off refining the code rather than the documentation.

And that's fine.  Changing code because it would be too embarrassing to
document it is certainly a better option than leaving it undocumented.

-- 
David Kastrup