piclist 2009\02\17\074343a >
Thread: Positive experiences with software development
picon face BY : Gerhard Fiedler email (remove spam text)

Vitaliy wrote:

{Quote hidden}

I have given examples before, one was a billing system for a company
with complex billing procedures. There are many projects that include
lots of requirements documentation that is not based on assumptions and
that is created prior to the start of (and sometimes partly during)

>> {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.

Well, then I've done the impossible. I can assure you, though, it's not
as impossible as it sounds... there are things that can (and should) be
documented that are not based on assumptions. Whether you draw it on a
whiteboard and take a picture or whether you use OpenOffice doesn't
really matter that much, for the end result.

>> { Document the areas where you would have to make them as "TBD" or
>> whatever, [...]

> 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.

So don't. I have worked on projects where there were man-years spent
documenting the requirements, and it was important and necessary that
they did so. And I have worked on projects where it was equally
important and necessary, but could be done rather quickly. Some of this
usually does change later, but with good documentation it's so little
that it doesn't affect the value of the documentation and the time spent
creating it.

You may not have experienced such situations, but that doesn't mean it's
not possible. It may be a limitation of your experience.

> 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, [...]

Of course there are "certain types of documentation" where this is true.
It should be evident that I'm not talking about that type of
documentation. The thing is that you seem to state that up-front
documentation is /never/ useful. This is something different, and our
collective experience seems to say (well, at least mine does say so)
that there are cases where it is.

I didn't say that there aren't cases where unnecessary or unsuitable
documentation is created. I know there are, I've seen them myself, and
never disputed this. But this doesn't mean that there can't be useful

Remember, it's you who's saying that there can't be useful
documentation. Citing examples of useless documentation is not making
this point, as long as there are examples of useful documentation. You'd
need to show why the documentation in the examples where it is thought
of as useful isn't useful after all.

> There's a huge difference between "documentation" in the traditional sense,

I think this is one of the core problems. You seem to see everything
we're talking about here in a "traditional" vs Agile sense, whereas we
others are really looking at all this in a rather non-ideological way.

So when I say "documentation", I mean "documentation". I don't mean
"documentation in the traditional sense" -- whatever you mean with
"traditional". What do /you/ mean with "traditional"? Why do you think I
mean /that/? It's as if you were thinking that we all are here trying to
convince you that the Waterfall model is better than the Agile model.
We're not (at least I haven't seen anybody trying this).

> The value is in transfering meaning from one person to another person.

This is exactly the value of documentation. I'm talking about
documentation that does this, not about any other kind. Whenever I
create documentation, this is (part of) what I work towards. I thought
the context made this very clear. How did you get the idea that this
might not be the value of the documentation that I'm writing about?

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

That's easily possible. It doesn't affect, however, the fact that
refactoring is expensive -- and an unnecessary cost if it could have
been avoided by reasonable thinking ahead a few iterations.

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

It's this what seems to be ideological double-speak you're using here
that is making this discussion so difficult. When you document
something, you call it "communicate". (Making a photo of a whiteboard is
"documenting". Creating a UML model is "documenting".) When I say
"documentation", you read it as meaning "traditional documentation" (for
whatever you think is "traditional", but in any case you seem to think
it's something bad). I never said that it is this what it means, and I
already have explained that I don't think what you seem to call
"traditional" is traditional at all. This change of meaning doesn't

When you're creating your own language, your own definition of terms,
you need to define them before use, otherwise others really won't
understand you. This is always the problem when ideology and a
ideology-based vocabulary come into play.

[FWIW, most other people seem to consider UML a "method used to specify,
... and document" software. The Wikipedia article about UML doesn't
mention "communication" at all. (Well, it does mention it, but a
different kind of it; not the one you're talking about.)]

While for your specific situation, all what you say and like about Agile
may make sense, you asked us about /our/ situations. And they seem to be
different enough so that some of your affirmations just don't hold. As
contract developer you get to see many different companies, many
different types of projects, many different types of team dynamics, many
different constraints, in all areas of a project. If we live long
enough, we probably see projects tank /because/ they used Agile methods.
(Of course the /real/ ideologue always says "that's because they didn't
use it right", but if we live long enough, we may even see some of them
get through that, too... :)

<7uu9aacztrh3$.dlg@connectionbrazil.com> 7bit

In reply to: <35634EA61CC846AE879AF986F8255196@ws11>
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...