Subject: Re: docs
From: Paul Rohr (paul@abisource.com)
Date: Fri Apr 20 2001 - 15:03:47 CDT
At 10:28 PM 4/19/01 -0400, Dom Lachowicz wrote:
>I've actually learned this from my various jobs, not school ;-) I've learned
>(the hard way) that Spec/Doc is absolutely essential to a project. No way
>around it.
I agree that there are lots of things specs and docs are very good for.
Good ones are always expensive to produce, but they're especially valuable
as a way of handing off unfinished work.
My only point is that good implementations are even more expensive to
produce. Given our "budget", we had to make choices like this every day.
>>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.
>
>It is impressive. But from a maintainance viewpoint? Absolutely horrible.
>Considering that I want to rewrite a new backend, knowing some of his
>throughts/assumptions in english (not C++) would be extremely helpful.
If you want to know how piece tables work, do some Google searches on the
literature. That's all we had when we started. You're three steps ahead of
us.
1. You have the sources to a complete working implementation.
2. You have some draft specs that started that implementation.
3. You know personally the folks who did that work.
BTW, why in God's name would you want to rewrite the PT? They're easy to
use, but a bitch to write and debug.
>>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.
>
>I'd rather have both. And half is being generous.
OK. Next time I start a massive coding effort with someone as talented as
Jeff, I'll try and add a "clone him to do better docs too" line item to the
budget. Anyone else I should plan on cloning? :-)
>>We wanted to prove it could be done, and we did a damn good job at it.
>
>Hell yeah!
Thanks. I just wanted to make sure that your understandable desire for more
docs is tempered by the reality of the price of those docs.
We had Jeff full-time for a year. During that time, he wrote a huge amount
of beautiful code. He writes some of the most useful comments about
critical design assumptions in tricky portions of his code that I've ever
seen. He also has been known to take the time to write up initial design
assumptions as HTML instead of just in email or on his whiteboard. Yes,
they're dated, but as soon as you realize that, they become useful again.
If he'd spent significant portions of that time writing more docs instead of
the mix of code and docs we got, I claim that it would be a *huge* net loss.
The only one who could convince me he could have done a better job of
optimizing his time is, frankly, Jeff.
>>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.
>
>True. The learning curve drops though, provided with the proper tools.
>That's all I'm saying.
Agreed. All I'm defending is the decision of an expert like Jeff to
maximize his productivity then, rather than your productivity now.
After all, it's not like we've made you dive into the thicket of Open Office
or the original Mozilla. The PT code had only a single author and is
remarkably consistent in its overall approach.
>>Paul
>>motto -- an implementation is worth 1000 words
>
>Dom
>motto -- most times, 1000 description do more to help understanding than
>30000 lines of implementation - and faster, to boot
Certainly. I still know which I'd choose:
- 30000 lines that Just Work or
- 1000 lines of description and 20000 lines of unfinished implementation
Jeff happens to be the kind of person that I can bet on the former and win.
Paul,
unrepentant :-)
This archive was generated by hypermail 2b25 : Fri Apr 20 2001 - 14:56:13 CDT