Positive experiences with software development
Gerhard Fiedler email (remove spam text)
1- There's no magic in documentation (nor in anything else). It needs to
be good, helpful, and the adequate measure. The magic is in these.
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.
Imagine starting on the firmware for a transmission controller. There
are many man-years (I know, I know, but it's still a useful measure to
indicate the complexity of a project) of development effort in such a
controller. There is /a lot/ of knowledge around about the specific
model of transmission for which you write the controller... but neither
the many guys who have that knowledge (either in their heads or in their
document collections) nor the many guys who need it (the programmers)
know at any given time what it is that is needed. The ones who have it
don't know what's needed because they don't participate in the
programming (they have other things to do, you know :) and the ones who
are programming don't know what they should know because they don't know
what there is to know. So a good documentation about the transmission,
what it can do and what it can't, the limits, the requirements for
operation as designed, the gotchas to watch out for... all this needs to
be documented, somewhere, somehow, and the programmers really should
read all that stuff before thinking about the first line of code.
Otherwise they really don't have a clue what it is that they should be
Or imagine a billing system for an insurance company, with hundreds if
not thousands of rules how to bill policies. These rules grew over time,
they are not consistent, but they don't want to piss off customers by
changing the rules just to make them (internally) more consistent.
Before you don't have a good picture of what is required, it doesn't
even make sense to start on the UI, because you don't know how the data
is connected, UI-wise, before you don't know the billing rules and the
possible transitions between them -- the transitions are where the
people need certain data, and if the UI doesn't provide this, it's just
crap. So you need all the rules before starting to create a concept.
This better be documented, completely and with a useful structure, so
that it serves as both an introduction to get the picture and as a
reference when you need the details while coding.
There is no magic in this, but certain documentation is simply
necessary. Of course there are programming projects that are so trivial
that you can explain the main function in fifteen minutes, in a
conversation, and don't need any documentation. But these are not the
ones on which larger teams work -- which are the ones where you really
need good management. The projects that have requirements you can
completely convey in fifteen minutes conversation probably don't need
much management at all; the probably only thing these need is a
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. For two reasons (and
no, a law suit is not among them): 1- to get a structure into the whole
talking and collect all the details while memory is fresh, and 2- to
have a common base for memory refreshing later. This is not about saving
one's behind, this is about keeping good relationships. It's all too
easy that a party feels betrayed at some point (this may even be you),
and having a common memory refresher (aka documentation) can be a
tremendous help in trying to solve the situation without any bad
feelings afterwards. (Which probably works similarly in bigger
> There is no such thing as perfect communication.
Agreed. There is no such thing as perfect anything.
> The knowledge is stored in the members of the development team, it's
> the so-called "project story". When all the developers leave, the
> story is lost, no matter how much documentation they leave behind.
> The new team has to develop its own project story. They may use the
> documentation the old team left behind, but the story will be their
Again, with /relatively/ trivial projects, this works, but not with more
complex projects. With more complex projects, there is no single project
story; there are many different stories. But there is a need to bring
all this together, and the only way to kind of know where each of the
ten smaller teams you have on the project is going, and not only /now/
but still a year from now, is to have some kind of distillation of their
"story" written up -- which is what I call "documentation".
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. Not
documenting the mathematic algorithms and their limitations is also not
good, because that would mean that all users of the program would have
to read the code and figure that out by themselves. Or you have someone
writing user documentation and say that's their job; but they generally
are not coders either, and even if they were it wouldn't be efficient to
let them find out what the coders thought when writing the code. So,
this would be a case where documentation of the underlying principles of
the code is quite adequate and probably necessary.
I really can't believe that you're trying to argue that documentation is
not necessary, ever. Don't you read data sheets? What's different about
> 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. I'd like to see how this would work out if Microchip
stopped publishing data sheets because somebody in there got convinced
that this isn't efficient, and instead insisted to convey the ideas that
up to then were presented in documentation now in Agile meetings between
the chip developers and the chip customers. I for one would buy from a
different company, even though for some others this would certainly
bring deeper insight than data sheets do.
>> There's also the situation where you need to have enough
>> documentation to be able to show that a failure was not your
>> problem, that it originated somewhere else. This can be quite
>> important, both in terms of client relationships and commercially.
> I don't doubt your statement is true in many situations, but it is
> sad nonetheless. Instead of delivering working software, programmers
> are forced to cover their behinds with lots of useless paper.
It's not useless. There are many programmers who don't have a clue what
they are doing... if you ask them what they accomplished last month,
they just shake their shoulders. Not their problem, they probably think,
because they get their paycheck anyway, and making sure that what they
did last month makes sense is the job of their manager.
Others, OTOH, know what they accomplished last month, and the month
before, and so on -- because they keep records (a form of
documentation). That this sometimes saves one's behind is a side effect;
the primary effect is that you keep track of what you're doing, where
you are efficient, where not, and /learn/ by doing this. It can be a
real eye-opener to write down what it is that you accomplished, as
opposed to just kind of feel you know it in your head.
Documentation is a learning process, both writing and reading. If it
isn't, there's something wrong with that specific documentation, but not
with documentation as principle.
>> But in my experience it's a minority of team members that take active
>> roles in such sketching meetings. It's not everybody's thing to
>> speak out ad-hoc thoughts in front of a group. If you want to
>> leverage the ideas and experience of these people, you need to
>> provide a different setting for them.
> Active participation can be defined as listening and watching other
> team members discuss the design.
Of course you can define it as that; you can define words as long as you
want. 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. 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".
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.
> The beauty of the whiteboard is that everybody sees the same thing at
> the same time, and it's easy to point at what's been written/drawn.
Again: for some, definitely, but not for all. There is also the definite
chance that certain personalities take over the space, and others stay
out. You can say "screw them, they should fit in and just work with
whatever I think works best" -- but I thought that Agile meant to take
the programmers for what they are, and work with this? If someone can't
come out with his ideas in such a group setting, provide a different
setting. Isn't this more Agile than defending the group whiteboard
sessions as something that people should adapt to, because it's a
commonly recommended Agile practice?
>> Agreed. However, also here is a balance. There is code that is
>> difficult to refactor, and a refactoring that takes a week, say, may
>> take a month or two of lots of testing and occasional debugging to
>> get to the stability the code had before. Now it's better, because
>> better structured, but what I'm saying is that refactoring is not
>> always as inexpensive as it looks.
> I would argue that refactoring has a net benefit, because the cost of
> *not* refactoring is usually high.
Again: there is a balance. What I was trying to convey is that the
/coding/ work of refactoring may be a small part of the overall effort.
A coding effort may be one man-week, and the associated testing and
debugging effort to get to the same stability (albeit with a better
structure) may be many man-weeks.
I agree with you that there is generally a net benefit. But there are
two things to consider: 1- it may be a long time until that "investment"
amortizes itself, and 2- you may have more important and more urgent
things on your plate, with a much shorter period of amortization and a
much higher potential for damage.
> If a customer reports a bug, and the code is such a mess that you
> can't find it, you lose future business. If the customer asks you to
> implement a new feature, and you tell them you can't because it'll
> break your existing spaghetti code, you lose money again.
Right. But usually it's not the question whether to refactor or not; the
question is usually whether to spend the required effort with that
refactoring -- or to do something else. And now it's not anymore about
whether refactoring is "good" or not, it's about whether it is better
than that "something else". And this decision now depends on that
This seems to be one of the underlying misunderstandings we seem to
have. It's not whether something is good or not; I already wrote that
most things have their place, and in that place they are good. (You
mentioned in another email hardcoded literals... you may be surprised
that I do use them, for example in short-lived debug code, or in quick
prototyping code. IMO they do have their place, even though I don't
recommend and don't use them in code that is meant to live for any
relevant amount of time.) 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
> 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.
> That's the whole point, isn't it -- figuring out what works in a given
> situation. You can't possibly try everything, so you need to make
> educated guesses what is likely to produce the best outcome. That's
> what I was asking about, but you guys don't seem to want to share
> your hard-won knowledge...
I'm trying to, but you seem to try to shoot down every bit of my
hard-won knowledge that's not in alignment with what you seem to be
doing. What I shared with you, you call "useless", you don't "believe in
the magic" of it, it's "sad", you figure you "lose money" with it, you
redefine "not getting input" as "active participation"... I don't quite
understand whether you want my "hard-won knowledge" or not. I don't have
a problem with you not agreeing with me, but it feels a bit odd that
you're saying that "we guys" (which seems to include me) are not willing
to share. It rather seems you are not willing to pick up what I spend
considerable effort placing in front of you.
In reply to: <22E7F9AC3E504E808B53E57D217C6303@ws11>
See also: www.piclist.com/techref/index.htm?key=positive+experiences
You must be a member of the
piclist mailing list
(not only a www.piclist.com member) to post to the