On Fri, Nov 12, 2004 at 09:14:42AM -0500, Graham Fawcett wrote:
> Granted, Martin. My response was that of a lazy person, and one who
> underdocuments his work. ;-) You're right: documentation writing is not

I expect that most of us do that.  It's at least partly sensible: as
you're working on it you mostly don't need to docuemnt things.  If you
are, in addition, groping around the solution space - I've been doing a
lot of adapting to messy data I have no control over but need to use
these last couple years - it's probably sensible not to spend too much
time on writing down many details.  OTOH, I do find that a few key notes
(or sketches, or entity-relationship diagrams, whatever) turn out to be
worth their weight in gold - an observation made long ago by Brooks in
_The Mythical Man-Month_.  With them, I can make sense of the code
fairly easily; without them, I would have to recreate them, more or
less, in the course of puzzling out the meaning of the code.  No, code
isn't documentation in any important way.

[it occurs to me to agree that test cases do make code more useful as
documentation, but IME it's still at a fairly low level.  that is, good
test cases will remove a lot of ambiguity about nuts'n'bolts level
details, but that's only one role documentation plays]

> best left to those who are struggling to discover a system (though these
> folks can make valuable contributions by identifying holes in existing
> docs).
>
> If not the Wiki, then what?

Well, actually I think having the docs on the wiki would be a good
thing.  Your comment about pushing the job off entirely on those who
most need to read them pushed a button that's been recently sensitized.

And there's at least one respect in which people who are just learning,
eg., Quixote *can* be especially valuable.  They can tell us what parts
aren't making sense, and some of them may be able to improve the docs
once they've been brought to understanding.  OTOH, one thing which I
think is frequently a real weak point in documentation is conveying the
overall scheme of things (and this is the part of the button that that
other conversational branch hit: code-as-doc is just piss poor at this,
and if you look at XP as a whole you can get some idea of the huge cost
they feel (rightly!) they need to pay to make up for adopting that
stance).

Joy.  Now I've gone and smashed both branches together and made a
wonderful mess!

> Perhaps it would make sense to fold the Quixote documentation into
> CVS? Developers are not always the best documenters, but at least CVS
> would provide a consistent platform for checking in changes to
> documentation as well as code changes.

Depends on the format of the docs.  I haven't actually looked at them
much since back when I was first gettign to know Quixote, but if
they're still pretty much the same sort of ASCII text documents I
remember (and that form is their "source code" format) putting them on
the wiki might be an appropriate move.

> those-who-cannot-write-docs-write-code-instead'ly yours,

Oh no you don't!  Those who write code *have* to be part of the
process.  At the least, they can best explain, at least to some users,
how things work; more importantly, they're the only ones who can
describe how things are *supposed* to work (code will never tell you
whether that odd behavior is intentional or a bug) or what direction
things are headed (code cannot tell you which behaviors are intended
and which are liable to change when a bug is fixed, or an intended
feature added or altered).

Hmmm, what's that other thing in .Sig.d that ought to be mentioned
here?    Oh, of course!

--
Show me your flowcharts and conceal your tables, and I shall continue
to be mystified.  Show me your tables, and I won't usually need your
flowcharts; they'll be obvious.  -- Brooks