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

Vitaliy 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). You may be working on a
project where the requirements are not sufficiently known; then rather
than assuming requirements that aren't, it's better to get a clear
picture of what would have to be known at some point to get to a
satisfactory solution and what is not yet known. (FWIW, this is
something that can (and has, in my past) kill the whole project; the
people who wanted something simply didn't know that they didn't know
enough about what they wanted. And that it would be too expensive to get
there.) Or you may be designing the architecture ahead of time, when you
have too many assumptions to make.

Base line is: when documenting, don't 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.

> In the end, the docs were too volumnous, too detailed, and too far
> removed from the real world.

Of course... if you make assumptions when documenting, you're not
documenting, you're speculating. And speculations are too volatile to be

And, obviously: the more speculations one has to make to get started,
the shorter the scope (or higher the "padding") of the contract, if
there is one, and the shorter the iteration cycles.

{Quote hidden}

They are not that different, in many cases. For example, the
transmission documentation, or the billing system. When you come into
the company to be hired to write the controller or the billing system,
usually the necessary knowledge is /not/ documented in a form suitable
for programming. Collecting this knowledge is part of the work to be
done, part of the project to be managed. Managing a programming project
is not only about managing the coding phase, it is about managing the
whole process. If I had only accepted work where there was sufficient
"user documentation" about the environment the program had to interface
to, I think I wouldn't have done a single project.

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

It seems you and I don't seem to talk about the same thing when talking
about documentation. When I say "documentation" I mean "pertinent and
current knowledge written down". You seem to be talking about something

For example, if a controller that I am about to design needs to work
from -40°C to 150°C, it may not help much when I start out with a
commercial temp range in mind; the design may not "scale" to that temp
range. There are similar questions for programs. So to gather what is
/known/ (no assumptions) is IME a good thing, and every hour that you
spend finding out what's known and delimiting what's not known /before
coding/ is well spent and will save many more hours later, during

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

I've never seen a project with too much documentation. There was almost
always a lack of (useful) documentation. The wrong kind -- this I agree

>> Besides, if you ever should take up a contract job, and even a simple
>> one, I highly recommend that you document whatever was talked about
>> and share this documentation among the participants. [...]
> 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).

As I said, this is not always practical. Some projects only make
(business) sense if they get to a certain feature and functionality
threshold within budget. There is no business value in any of the
iterations until that point. It's very difficult to convince people to
commit resources to me if I can't or don't want to commit to getting

It's a market thing. If someone commits to getting there for the same
price I'm estimating, they'll go with the one who commits to it. More
business value, at that point, in that contract.

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

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.

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

Ok, we agree on that. I just thought that you had said that
"documentation is not useful" or something the like, not "documenting
the wrong things is not useful" or something the like.

{Quote hidden}

This is not a problem, it is a feature. (That is, it can become a
problem if used inappropriately.) The features are that the same
document can be read by many at the same time, that it can be read
whenever it is convenient for everybody who is interested in the
contents, and it can be read and re-read and re-re-read. All these
features are not present in person-to-person communication.

I agree that paper has some problems; in general, I prefer documentation
in electronic form. (In all this exchange about documentation, I never
ever mentioned paper, so this is really barking up the wrong tree here.)
But then, there can't much be said against spending a day in the hammock
reading a lengthy requirements document :)

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

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

Good thing, agreed.

> What you mean is, you need other forms of communication. I agree.

That exactly it.

> I thought you were saying that "whiteboarding" doesn't work because
> only minority of people participate (which I don't agree with).

Nope. It's a good thing, and I think every software company I worked
with or for (since the 80ies) had a whiteboard.

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

No. As I said previously, I agree with most of the Manifesto, and I
agree with many of the techniques that are currently considered the
grail of Agile. But I think that there are situations that call for
approaches that hardcore Agilists despise: waterfalling requirements
before coding, using Gantt charts for documenting task relationships,
stuff like this -- when and where appropriate. And this is why I wrote
what I wrote at the beginning: for me, it's not about following any
school of project management (too many, and as good as anybody may think
Agile is, it's not the first and I'm rather positive that there will be
others), it's about learning from them and using their tools (from all
of them) when and where appropriate.

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

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

The perspective of where one comes from can change the view
dramatically. For people who didn't use to refactor, refactoring sounds
really nice when they discover its power. For people who created a new
architecture every other week, the potential of leaving some code alone
when it works well enough can be a real eye opener :)

But IME the latter are not that common. Most programmers will just hack
onto whatever is already there; it seems this is some kind of avoiding
taking responsibility. If it's already there and doesn't work, it's not
their problem; if they refactor it and it doesn't work, it is their
problem -- or something the like. Besides, before refactoring you have
to make sure you understand everything the previous code did -- right
and wrong, which is also something some programmers shy away.

So, in total, I think a good emphasis on refactoring is good, but
keeping the perils and downsides in mind doesn't hurt either. And being
aware that some programmers need to be discouraged :)

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

Well, besides saying this, I did say some other things, too -- like that
I think that good documentation is useful, that getting a good grip on
requirements (and document them) before jumping into the first iteration
of code is useful, that the group sessions at the whiteboard are not a
way to get everybody's input, and so on.

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.

<pc0uoovrv4y4.dlg@connectionbrazil.com> quoted-printable

In reply to: <2883D9AFEE3C4F3EBA3FB6B5D968678C@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...