piclist 2009\02\17\031714a >
Thread: Positive experiences with software development
face BY : Vitaliy email (remove spam text)

Gerhard Fiedler wrote:
>> 2- If you spent six man-months and it didn't help in the end, either
>> the documentation wasn't good, or it wasn't documenting the right
>> thing, or it was too much.
> The problem was, we tried to document every detail, before anything
> was built. A lot of assumptions had to be made.

{When you have to make assumptions, you are /not/ "documenting" (what
is), you are speculating (about what may be). }

Isn't that what all specs are about, and why they change? Unless you're
talking about documenting "after the fact", not during or prior to the start
of development.

{Base line is: when documenting, don't make assumptions.}

Impossible: you would have to be able to predit the future in order not to
make assumptions.

{ Document the
areas where you would have to make them as "TBD" or whatever, so that
you know that there is a spot to be filled in -- but (did I say this
already? :) don't make assumptions when documenting. That's contrary to
the purpose.}

Then the whole document would have to be "TBD". You're saying that once you
document something, it is set in stone. I don't believe this for a second.

[snip snip snip]

{It's never about "everything or nothing", it's always about measure.
This is the same as learning in general. If I have a document that
clearly states the hard requirements and boundary conditions, I can give
that to a new team member and say "read it", and after that assume that
she's reasonably familiar with it. (This can be before or after a short
introduction.) The conversations afterwards have more substance. Have
you heard "a picture says more than a thousand words"? Pictures are
documentation, you don't speak in pictures, you speak in thousand words.}

Documentation often consists of many thousands of words. :) And it is quite
possible that with certain types of documentation, you are better off
spending 30 minutes explaining the system to each new member of your team,
than writing the documentation in the first place (and spending the time to
keep it in sync with the evolving system).

{ You can draw a picture on the whiteboard, but when you find yourself
drawing the same picture for the third time, it may be time to think
about documenting this picture, so that you don't have to redraw it all
the time. }

I take a digital photo, and print it. Takes very little time and effort.

> There is documentation in the form of notes from previous meetings and
> sprint backlogs, but it is mainly intended for outsiders.

{ Didn't you just try to make the point that documentation is the worst
form of communication? Apparently it's not, or else nobody would spend
valuable time taking notes. It is these inconsistencies that pop up when
reading your descriptions of Agile techniques. }

I don't know why it is so hard to explain such a simple concept.. I now
think that maybe email is the worst form of communication. :)

There's a huge difference between "documentation" in the traditional sense,
and note-taking in the agile sense. Note-taking takes the form of sketches
on a piece of paper (as the speaker is making his point), or scribbles on
the whiteboard. The difference is where you think the value is: in the
artefacts that are produced, or in the process of making the artefacts.

We do a lot of writing and drawing on the whiteboard, especially during
project brainstorming sessions, not because we want to produce something of
value (documentation in the traditional sense), but because it is a very
effective form of communication. The value is in transfering meaning from
one person to another person.

> A lot of times I go for the "quick change" without refactoring. I put
> off refactoring until I either have the time (i.e., feel like it), or
> I'm forced to do it. I think it's similar to not washing dishes, or
> not paying off the balance on a credit card every month -- you can
> put it off, but at some point you have to do it. And the longer you
> wait, the worse it gets.

{ But, differently from credit cards and washing dishes, with refactoring
it really happens that you put it off and find out that you'll never
have to do it -- because you won't ever have to touch that part of the
code again. Maybe because it works well enough for the purposes of the
product, or because the product is scrapped or replaced before the not
refactored part had a chance to become a critical problem, or whatever. }

I don't know, I end up refactoring most of my code at least once. :)

{ FWIW, I find a similar fervor as you show it when it's about Agile from
some people using UML. UML is all about project documentation, and some
people swear it has increased their productivity dramatically, that it's
the best invention since sliced bread and so on. I don't use it
generally, I've never used it in a big project, but I can imagine that
it has its place. Just not (yet?) in my toolbox. There are also a lot of
smart and experienced people behind it, but it seems to be quite
diametrical to Agile. Which is not meant to say that either is wrong,
but that several bunches of smart and experienced people can go in quite
different directions. }

I use elements of UML, to me it's just a common way of communicating. Kind
of like transistor and resistor symbols.


<35634EA61CC846AE879AF986F8255196@ws11> 7bit

See also: www.piclist.com/techref/index.htm?key=positive+experiences
Reply You must be a member of the piclist mailing list (not only a www.piclist.com member) to post to the piclist. This form requires JavaScript and a browser/email client that can handle form mailto: posts.
Subject (change) Positive experiences with software development

month overview.

new search...