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

Gerhard Fiedler wrote:

The post is getting very long, I'll do my best to condense, let me know if I
leave out anything of importance. :)

> 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. In the end, the docs were too
volumnous, too detailed, and too far removed from the real world.

> Imagine starting on the firmware for a transmission controller. [...]
(Also, you mentioned Microchip datasheets, and a billing system for the
insurance company)

We're talking about two different kinds of documentation. I'm talking about
project documentation (for lack of a better term), basically what you use to
build your project, the implementation details useful only to the

You, on the other hand, appear to be talking about user documentation. As a
user, I'm all for documentation -- the more, the better! As long as the
information I need is easy to find, of course. :)

However, I am against unnecessary project documentation. I am especially
strongly against creating detailed project specifications early in the

> There is no magic in this, but certain documentation is simply
> necessary. [snip]

No argument there. I would argue, however, that nowadays the problem is too
much documentation, or the wrong kind of documentation.

{Quote hidden}

Sure, absolutely. However, I would probably ask to limit the scope of
discussion to what is relevant for the near term (until the next iteration).
Cover the big picture as much as necessary, but when it comes to hashing out
the details, don't focus on implementation details of features that won't be
implemented in this iteration (until the next meeting). Requirements are
likely to change by then, the feature may become redundant, or the system
may change to the point where the docs would need to be completely revised.

>> There is no such thing as perfect communication.
> Agreed. There is no such thing as perfect anything.

In theory, there is. ;-) I think the problem is not the fact that
communication is not perfect, but that people tend to think it is.

{Quote hidden}

OK, as long as the assumption is not that someone totally unfamiliar with
the project would be able to use the documentation to learn everything they
need to know about the system.

> Now, that "documentation" of the story of a programming team can be
> well-documented code. Or it may have to be something else; this depends
> on the specific task. For a team working on mathematic algorithms to
> solve something, documenting in code the algorithms used and their
> limitations may not be the way to go... ASCII is not really helpful
> here, so using a different method is probably much more efficient.

Sure, I'll buy that. :) In fact, we keep notes with "expected waveforms",
which also do not lend themselves very well to ASCII representation.

> I really can't believe that you're trying to argue that documentation is
> not necessary, ever.

I think that documentation is necessary, so I could not have argued that it
isn't. I thought we both already agreed that you need just enough
documentation (but not more), and it needs to be of the right kind.

> Don't you read data sheets? What's different about
> this?

No, my secretary reads it, and provides me with a summary. ;-) See "project
documentation vs user domentation" above.

>> The implication is that you shouldn't fixate on documentation, but
>> instead find efficient ways to communicate the ideas.
> If some specific documentation doesn't do this, there's something wrong
> with that specific documentation, not with the principle of
> documentation.

This is addressed in the Agile Software Development, and here is basically a
summary by Scott Ambler:


Paper is about the worst form of communication there is. I think its
fundamental problem is it's lack of interaction (it's all one way).

{Quote hidden}

I know you hate it when I mention Agile, :) but transparency is a big thing
for agilists. At any point in time, everyone knows what everyone else had
done, and if there are any problems. Every iteration (ideally, every two
weeks) the team looks at the sprint log, and asks:

- What has been done?
- What has not been done, and why? (external factors, took on too much work,
- What can we do better in the next iteration (sprint)?

Additionally, there are daily stand-up meetings (which last about 5-10
minutes), where everyone reports on their progress and any difficulties.

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

So the point is, instead of waiting until the end of a project to do a "post
mortem", you do the post mortem every two weeks (on a smaller scale, every

{Quote hidden}

"I reject your reality, and substitute my own". ;-)

> But I tried to convey the idea that there is some valuable input
> that you just won't get in that situation, and that you need to provide
> a different situation to get that.

What you mean is, you need other forms of communication. I agree. I thought
you were saying that "whiteboarding" doesn't work because only minority of
people participate (which I don't agree with).

> Of course, you may think you don't
> need that input, but I thought the whole objective of this conversation
> was to show what helps maximizing the efficiency of management efforts.
> Instead you try to shoot down every idea that doesn't fit in whatever
> group of techniques you think is the current definition of "Agile".

What? :-O

And I thought that *you* are trying to shoot down every idea that you think
has anything to do with Agile. ;-)

Seriously, I'm not married to Agile. I question some of its maxims, and I'm
open to ideas and criticism. If you can show me that my assumptions are not
valid, my ego will survive such eventuality unscathed.

> To restate it: it is my experience that there is valuable input to be
> had for some team members that won't come in such group whiteboard
> sessions. Other, more private settings are required to get that input.
> Do with this what you want... but if you ask me about my experiences,
> that's one of them.

And I appreciate you sharing it. Where I work, we try to maximize
communication by employing a variety of means of communication: team
meetings, one-on-one meetings, email, phone, IM, sticky notes on keyboards,
you name it.

{Quote hidden}

I'm sorry you got the impression that I advocate using the whiteboarding
sessions as the only means of communication. My bad, I was only saying that
it is one form of communication that we found to be very effective.

{Quote hidden}

Yeah, I'm with you. 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.

{Quote hidden}

Well sure, I do it too. :)

> The question is not whether something is
> "good" or not; it's whether, in a given situation, it is "better" than
> the alternatives. And this depends on the situation, the available
> alternatives, the criteria that define "better" etc.


> For example whiteboard... all nice and good, for certain types of people
> and situations. However, I often work thousands of miles away from other
> team members, and for me attending their whiteboard sessions doesn't
> quite work. So we adapt, use other methods, and it seems that this can
> work well, too. Doesn't work for and with everybody, but works for and
> with me.

I will only reiterate that Agile doesn't lock you into any particular
method. Use the most efficient form of communication available to you.

>> It's not black and white either: early refactoring is less expensive
>> than late refactoring.
> In simple coding time, yes. But not necessarily in product cost. For
> that, you'd have to also consider the cost of not doing what you could
> have done while refactoring. This is easily forgotten. In most
> situations, programming professionally is a zero-sum situation: if you
> do one thing, you don't do another.

You are right, of course, but I'm finding that lately I've many times
encountered situations where I chose to refactor the code before making
changes to it -- because of previous positive experiences (less time spent
chasing a bug). Other times, I felt like refactoring was the only option

{Quote hidden}

Gerhard, I'm really sorry you feel this way. It was not my intent at all to
"shoot down" what you have to share. All those things you quoted were not
directed at you. And the reason I said that it feels like you're not willing
to share your knowledge, was because you both seemed to say that every
project is different, and what works for one project does not work for
another project. Unless you expand on that statement, it does nothing to
increase my knowledge. :-)


<2883D9AFEE3C4F3EBA3FB6B5D968678C@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...