Subject: docs (was Re: XP design for image support)
From: Paul Rohr (paul@abisource.com)
Date: Thu Apr 19 2001 - 21:18:24 CDT
At 08:52 PM 4/19/01 -0400, Dom Lachowicz wrote:
>Thanks a lot. I know that you're a huge advocate of mailing-list discussion,
>searching back through threads to find docs/design decisions isn't exactly
>pleasurable.
Wow. I've been out of school *way* too long. I'm used to projects where
there's no written record of any sort. To have large chunks of the design
fleshed out even *once* in writing is, in my experience, a rare and precious
thing.
>We're seriously lacking all sorts of docs on the underlying
>design of Abi. Jskov has done well to get us at least inline Doxygen
>comments as a standard. There should also be more docs lying around (maybe
>with UML or Pics) about many/all of the design decisions.
All of those would be (and are) nice to have.
>All we have now is
>basically Jeff going "well, I'm going to write 6 pages of fluffy quasi-spec
>on a 30,000 LOC implementation of a piecetable."
Jeff was kind. He's good enough to have written a *damn* impressive 30,000
LOC without telling you anything about it it all. The spec corresponded
with the first few days of thought on the subject. Then he implemented the
rest and refined it until it did everything it does now.
Considering the extreme rarity of true bugs in the code he wrote, I have
zero problem with that. I'd certainly rather have all the code and half the
docs than the other way around.
>The (unfortunate) short
>story is that if we had to deliver this product to a client complete with
>Doc/Spec, we'd get sued.
Naw. Someone like that never would have funded this effort in the first
place. And they certainly wouldn't have paid for specs or docs. The only
reason this product exists at all is that people like Jeff and I went ahead
and coded like banshees for the brief window of time that someone *was*
willing to pay us.
We wanted to prove it could be done, and we did a damn good job at it.
>Why is this important? Well, who here helped Jeff write the PT? XAP vs. AP?
>
>/me searches for hands in the crowd
>
>Ok, so really no one besides Paul, who is an invaluable resource BTW :) So
>being the new developers/maintainers, it is absolutely *essential* to have
>these things lying around.
Oh, it certainly makes life easier -- if the docs are maintained
scrupulously, that is. Bad docs are worse than no docs, until you realize
they're wrong, at which point they become useful again.
There's no way around it ... it's work to have to drop into a codebase of
between 100K and 1M LOC and find your way around. It's a skill anyone in
the business learns, though.
Paul
motto -- an implementation is worth 1000 words
This archive was generated by hypermail 2b25 : Thu Apr 19 2001 - 21:10:48 CDT