Because we can't talk to the original person, in the orginal context, all
of this is of course idle speculation, but here's two thoughts that
Post by Tim KingI might as well have been talking to myself, though., because apparently
I had missed a critical phase of software development: all the
documentation that was necessary to describe the architecture.
This paragraph and the following one where the person couldn't find their
way around, sound like classic examples of spoken motive masking true
motive -- i.e. it sounds like he was using this as an indirect way to
avoid having to disagree with you(for whatever reason, he didn't agree
with your design, It didn't match his pet approach, he didn't want you
getting credit, he didn't want you to look more productive, he was more
comfortable with the old system, etc). In general, I often see people use
process points as a series of delaying and distraction tactics because its
a culturally acceptable way to stonewall an opponent (where opponent is
anyone whose success affects one negatively -- even in one's own mind).
This is doubly effective when the process point is only subjectively
verifiable.
Another thing I have seen is to use documentation to minimize
disappointment: If I spend four months writing the document, and then they
kill the project, I won't have invested myself into code that won't see
the light of day.
Still another possibility that I have seen is using documentation as a way
to work (i.e. put in your 8 hour day) without having to produce anything
that can be objectively criticized.
Finally, and probably my least negative one: some people seem to feel more
comfortable thinking, talking and writing about their designs than
acutally implementing them. In no small measure this is IMHO due to the
deeply ingrained cultural norm in software development that if you ever
have to revisit something it implies a failure in your first effort. By
documenting and delaying that first effort, you can procrastinate this
unpleasant happenstance. I wrote about this aspect of Agile development
way back in my second blog entry:
http://www.williamcaputo.com/archives/000002.html
As I said all speculation.
Best,
Bill
William E. Caputo
ThoughtWorks, Inc.
http://www.williamcaputo.com
--------
omnis cellula e cellula
Tim King <timk-***@public.gmane.org>
Sent by: xpbookdiscussiongroup-***@public.gmane.org
04/22/2005 12:41 PM
Please respond to
xpbookdiscussiongroup-***@public.gmane.org
To
xpbookdiscussiongroup-***@public.gmane.org
cc
Subject
Re: [xpe2e] Practice: Code and Tests
I asked, why use a documentation-first approach?
Post by Tim KingIt's an easy way to feel productive without the risk of failure.
This is what I thought at first, and I even for a while had up on my
cube wall a printout of WorryDrivenDevelopment from c2.com/wiki, which
elicited a couple of laughs before (I think) people started suspecting
maybe I didn't think it was a joke. :-}
True, I don't think it's a joke, but that's a different subject. While
this may have been a driving force, especially considering the corporate
culture (which I'll get to in a moment), I don't believe it sufficiently
explains this instance. Management indeed wanted documentation. But one
of the developers (with whom I no longer have contact) pushed for lots
of documentation up-front, much more than management needed.
Post by Tim KingInstead i think it may be a matter of working environment.
If the company usually changes its programmers the knowledge flows away.
Sometimes we hear a latin sentence: Verba Volant Scripta Manent.
The company does commonly foist multiple projects on each developer. And
it also physically seperates developers from each other. This in
combination with inter-departmental political barriers make
communication very weak and trust very difficult to establish. One of
means used to compensate for these weaknesses is formal documentation.
But this project involved only a few developers in a single group of a
single department. And the company keeps the same developers on active
projects, so the knowledge is usually there when needed.
Post by Tim KingI suspect it has something to do with comfort.
It surely may. I remember once I (unwisely) said in a meeting between
the three of us that we should wrap up, because "I have work to do."
This other developer took on a stern, passionate aire and said, "We ARE
working." I clearly had hit a hot button, in a very undiplomatic way.
But truthfully, though we were doing work, we weren't getting anything
done, nothing that could be delivered anyhow.
I even spent time generating a skeleton for the project. In a single
week, working alone, I constructed an end-to-end implementation that
actually worked. No, it didn't have all the whizzy features the final
software was to have. But it performed all the critical functions and
had pieces for all the architectural components. I used it to gather
statistics to prove the superiority of the implementation over a
20-year-old implementation we were working to replace.
I might as well have been talking to myself, though., because apparently
I had missed a critical phase of software development: all the
documentation that was necessary to describe the architecture. "Just
look at the code," I said. "For whatever's muddled in it, let's sit down
and look at it together." Nothing-- Except complaints that he couldn't
find his way around the codebase of a dozen classes (which were
documented), along with requests that I generate a Word document
explaining how the code works, followed by befuddled expressions on my
own face. I've never felt so much like a failure. And still, I don't
understand what it was that I missed.
Good developers, I guess, sometimes have honest differences of opinion
that can't be resolved.
Post by Tim KingCould you have a non-judgemental discussion with one of
the people who practice documentation-first and find out what their
conscious purposes and principles are?
I cannot have any further follow-up discussions, since the developer in
question is no longer with the company, and I have no way to contact
him. But I would be very interested in hearing what Carlton's colleagues
have to say.
Post by Tim KingThe recurring theme is that they want 'plan ahead' so they
won't make mistakes in design which will cost them...
I also heard this theme. And I think we all agree that we should
understand what we're designing before we design it. But source files
are not more difficult to change than Word files. In fact, the reverse
is true. Inevitably there will be big problems with your initial shot at
high-level design (and in this case, there were), and you'll have to fix
them when you generate code, and you'll have to update your Word files
if you want them to be correct. This is especially true when you start
listing function prototypes in design documents. Big documentation up
front is wasteful. Having been on both sides of this fence, I feel
confident in saying so.
Of course, this didn't seem to address the real issue, even though it
was a recurring theme in our discussions.
Post by Tim KingWe often assert that if a project is destined to last 6 months it will
last 6 months whichever way you choose to run it, be it XP or RUP or WE.
The difference is in the the project's residuals.
This assumes that you can successfully document a design before the
design exists. In my experience, this has never been true. You can
_think about_ a design before it exists. But once you start turning the
design into a working (or not) deliverable, you're going to discover
deficiencies that you'll need to correct. It's better then to keep the
up-front documentation only as heavy as it needs to be for intra-team
communication, because you're going to need to change it later.
(Note that in other engineering disciplines, the theory of operation is
written _after_ the design is complete and proven. Why do we insist on
writing the theory of operation first?)
Post by Tim KingYes yes yes yes. I have left out TONS of other good XP stuff. But then,
I also left out the warm fuzzies that management gets from all these
documents...
How about if I take my Doxygen or JavaDoc output and put it in a Word or
PDF file? I've actually been surprised at how much paper Doxygen and
JavaDoc can use up. ;-)
-TimK
--
J. Timothy King ..team-oriented..object-oriented..Agile..
www.jtse.com ..C++..Perl..Java..assembly..embedded.systems..
Yahoo! Groups Links