Searching \ for '[TECH] Positive experiences with software developm' in subject line. ()
Make payments with PayPal - it's fast, free and secure! Help us get a faster server
FAQ page: www.piclist.com/techref/index.htm?key=positive+experiences
Search entire site for: 'Positive experiences with software developm'.

Exact match. Not showing close matches.
PICList Thread
'[TECH] Positive experiences with software developm'
2009\01\31@035408 by Vitaliy

flavicon
face
"Gerhard Fiedler" wrote:
>> You pretty much evaded the question. Can you tell us about that one
>> time everything worked well, in as much detail as possible? :)
>
> No, I can't.

That's too bad. :(


> There isn't really much to tell. You make your experiences, and
> sometimes it goes better and other times it goes worse. And some of the
> better ones you think are really good. There isn't any magic [...]

I think after you've been doing something for a while, you start seeing
certain patterns, and identifying things that work, and others that don't.

I've been a part of two failed projects. One project failed because we
drowned it in documentation. The other one died mainly because we tried to
reinvent too many wheels, instead of using existing frameworks and
components.

Projects that succeeded, in general had the following characteristics:

- We jumped to implementation early in the project: to prove a concept,
build a quick mockup or a prototype
- There was lots of communication between developers
- Only the bare minimum of documentation was created, most of it of the
"sketch on a napkin" type.
- Many iterations, based on the changing requirements
- Version control, which acts as a safety net, and encourages risk-taking

On more recent projects, I found the following helpful:

- Weekly meetings with involved parties
- Sketching out the design on a whiteboard. We have two big ones in the
conference room, and they're both used quite a lot. To save the notes, we
take a picture with a cheap digital camera, crop it, crank up
brightness/contrast, and print the result. The printout looks like
handwritten notes (fooled several people already).
- Refactoring is the way to keep code maintainable, and is usually what I
resort to when I dig myself into a hole
- Object Oriented design, which is even possible in C
- Writing code in the most straightforward way, even at the expense of
performance/code size when necessary

Oh yeah, and of course great books on project management, software
development, writing good code, and design patterns where a lot of useful
ideas originally came from.


> Whoever thinks that this is so bad should probably look for a different
> line of work. I don't have the impression that it's worse than in any
> other area.

I don't think it's all that bad, but I do think there is much room for
improvement. I would love to hear what tools/techniques/practices other
people find useful in their work.

Vitaliy

2009\01\31@042133 by Philip Pemberton

face
flavicon
face
Vitaliy wrote:
> - Sketching out the design on a whiteboard. We have two big ones in the
> conference room, and they're both used quite a lot. To save the notes, we
> take a picture with a cheap digital camera, crop it, crank up
> brightness/contrast, and print the result. The printout looks like
> handwritten notes (fooled several people already).

Speaking of whiteboard image extraction.. I've been (slowly) hacking away at a
program that takes a JPEG file containing a photo of a whiteboard, removes the
brightness variations caused by light shining on it, makes the background pure
white, and enhances the contrast so you can see the text properly.

It's based on an algorithm published in a research paper in Digital Signal
Processing, Vol.17, No.2 by Zhang and He. I never got round to implementing
edge-detection, but I did get white-balancing, contrast-enhancement, and
squaring working (you have to select the corners of the whiteboard for that one).

It's a neat toy, and was useful for getting useful notes from certain
university lecturers who always erased the whiteboard before everyone had the
notes written down!

--
Phil.
spam_OUTpiclistTakeThisOuTspamphilpem.me.uk
http://www.philpem.me.uk/

2009\01\31@113550 by Gerhard Fiedler

picon face
Vitaliy wrote:

>>> You pretty much evaded the question. Can you tell us about that one
>>> time everything worked well, in as much detail as possible? :)
>>
>> No, I can't.
>
> That's too bad. :(
>
>> There isn't really much to tell. You make your experiences, and
>> sometimes it goes better and other times it goes worse. And some of the
>> better ones you think are really good. There isn't any magic [...]
>
> I think after you've been doing something for a while, you start
> seeing certain patterns, and identifying things that work, and others
> that don't.

Until you find yourself in a situation where something that didn't work
works.

> I've been a part of two failed projects. One project failed because we
> drowned it in documentation.

I've seen that, too. But I've also seen projects go well because of
extensive documentation -- and I've seen projects not go well because of
lack of sufficient documentation.

I've seen it quite often that my initial progress is slow. I tend to dig
myself into the problem, digest it for a while, and this may take weeks
without a single line of code. But when I start on it, there are only
very few surprises, and possibly none that requires a change of
direction.

It's always a matter of the right measure.

> The other one died mainly because we tried to reinvent too many
> wheels, instead of using existing frameworks and components.

This also happens, just as its counterpart: spending too much time with
existing and known frameworks, just to find out at the end that the work
to coerce them to do what you need to do is much more than a proprietary
solution would have been. Tends to happen when sufficient pre-planning
wasn't done.

See, this is one nice example. In order to decide whether the (sometimes
substantial) effort to start using a certain framework is worth it, you
need to plan pretty far ahead and know the final requirements rather
well, or else you may find yourself with a lot of investment in a
framework that just doesn't get you where you need to go.

> Projects that succeeded, in general had the following characteristics:
>
> - We jumped to implementation early in the project: to prove a concept,
> build a quick mockup or a prototype

Is good for some projects, not so good for others. There's the approach
that just doing it gets you somewhere quickly. There's also the approach
that an hour thinking and planning ahead can save you many hours later.
This is not an either-or situation, this is about the right measure and
applying the right approach to the right problem.

The projects I've seen failing usually failed because of a lack of
planning, mostly estimating. There are situations where it doesn't help
the project if you successfully create ten iterations that all do a
subset of what's finally required if you can't get to the full
requirements within budget. In those cases, the effort spent for the ten
iterations is simply wasted, because of a lack of planning. If the
minimum required is too much to do within the budget, don't even start
-- but this requires planning ahead.

> - There was lots of communication between developers

This is always good. The ten thousand dollar question is how to get your
team to efficiently communicate. Which depends a lot on the team and
many other constraints of the situation.

> - Only the bare minimum of documentation was created, most of it of
> the "sketch on a napkin" type.

Of course. To do it right, you always do the minimum required (in
engineering, at least). Everything beyond the required minimum is
ballast. But the problem is that the minimum required varies
considerably with the type of project. There are programs where what
they do, in principle, can be conveyed in a fifteen minute conversation.
There are others that are so complex that you need a few people working
on it for a year to gather what the program should do. If they don't
document what they did during that time, it's lost, and if they do, it's
a huge amount of documentation. And before they do this, nobody has a
clue about the scope of the work, so it's not possible to even talk
about a reasonable contract.

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.

> - Many iterations, based on the changing requirements

As I said above, this is a good thing in some situations, but it doesn't
guarantee the success. And again it's a question of the right measure.

> - Version control, which acts as a safety net, and encourages
> risk-taking

Right... now every software team effort that doesn't use version control
should better get a different manager or lead :) I thought this was
understood to be a basic thing.

> - Weekly meetings with involved parties

Nice to have, but geographical constraints may make this inefficient.

> - Sketching out the design on a whiteboard.

Is often helpful. I like drawings, and I don't have a problem of being
shown wrong in front of a group. 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.

> - Refactoring is the way to keep code maintainable, and is usually
> what I resort to when I dig myself into a hole

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.

> - Object Oriented design, which is even possible in C

I don't buy that this is important for success of programming projects
in general. It's possible, but I think whether it's helpful depends a
lot on the specific problem.

> - Writing code in the most straightforward way, even at the expense of
> performance/code size when necessary

Agreed. (FWIW, I think that whether OO is or is not the most
straightforward way depends a lot... on many factors.)

> I would love to hear what tools/techniques/practices other people find
> useful in their work.

I tried to convey this in my previous messages... Be flexible, look at
every aspect of the situation, get to know the people involved (this
includes you!) and their strengths and weaknesses, how they work and
what they need, like and dislike, and /adapt/. No matter whether a
technique is "Agile" or not... if it works in a given situation, it's
the way to go. There is a place for pre-defined requirements, ad-hoc
coding, Gantt charts, early prototypes, months of planning, programming
in couples, groups, and alone in your home, writing heaps of good
documentation, quick iterations... it really depends on the specific
situation. Don't be afraid to use a technique just because Turble
Bigshot wrote that it can't work :)

Gerhard

2009\01\31@125532 by olin piclist

face picon face
Gerhard Fiedler wrote:
> I tried to convey this in my previous messages... Be flexible, look at
> every aspect of the situation, get to know the people involved (this
> includes you!) and their strengths and weaknesses, how they work and
> what they need, like and dislike, and /adapt/. No matter whether a
> technique is "Agile" or not... if it works in a given situation, it's
> the way to go. There is a place for pre-defined requirements, ad-hoc
> coding, Gantt charts, early prototypes, months of planning,
> programming in couples, groups, and alone in your home, writing heaps
> of good documentation, quick iterations... it really depends on the
> specific situation. Don't be afraid to use a technique just because
> Turble Bigshot wrote that it can't work :)

Exactly!

I'm really tired of hearing one set of guildlines that have been used all
along suddenly given a fancy name and treated like gospel to the exclusion
of common sense tradeoffs.  As usual, the only hard and fast rule is that
there are no hard and fast rules.

A good example is Vitaliy's description of little up front planning with
many quick turn iterations that each show some results.  That can work for
some types of software, like GUIs where the end result is more important
than the structure.  Some personality styles work better when they can see
some results early on.  This also can be useful to show progress to many
customers.

However, it can likewise be a disaster.  This depends both on the nature of
the project and the people implementing it.  I've seen a number of projects
where lack of carefully planned architecture created a unmaintainable mess.
I personally am more of a architect and feel uncomfortable in the
slap-it-together-quickly environments.  That's not to say those types of
environments can't yield successes given the right projects, but that you
need different people for each and you have to know when each is
appropriate.

Good managers tailer the environment and rules to the project and the people
and a number of other harder to define parameters.  Hard rules, especially
collections of them with cutesy marketing labels, are the first refuge of
the incompetent.


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2009\01\31@165022 by Vitaliy

flavicon
face
"Philip Pemberton" wrote:
> Speaking of whiteboard image extraction.. I've been (slowly) hacking away
> at a
> program that takes a JPEG file containing a photo of a whiteboard, removes
> the
> brightness variations caused by light shining on it, makes the background
> pure
> white, and enhances the contrast so you can see the text properly.
>
> It's based on an algorithm published in a research paper in Digital Signal
> Processing, Vol.17, No.2 by Zhang and He. I never got round to
> implementing
> edge-detection, but I did get white-balancing, contrast-enhancement, and
> squaring working (you have to select the corners of the whiteboard for
> that one).
>
> It's a neat toy, and was useful for getting useful notes from certain
> university lecturers who always erased the whiteboard before everyone had
> the
> notes written down!

Are you willing to share the toy? :)

VItaliy

2009\01\31@171401 by Vitaliy

flavicon
face
Olin Lathrop wrote:
> I'm really tired of hearing one set of guildlines that have been used all
> along suddenly given a fancy name and treated like gospel to the exclusion
> of common sense tradeoffs.  As usual, the only hard and fast rule is that
> there are no hard and fast rules.

Well then it's pointless to continue this conversation, isn't it? Anything
goes, develop your software any way you like, no one way is better any other
way.

I sense a double standard, however. Both of you (Gerhard and Olin) at one
time or another advocated (very forcefully at times) a certain way of
programming, or a design practice. If software is an art, why do you get so
passionate about defending your vision of "the right way" to write software
(and why do I often find myself agreeing with it)?

"There are no hard and fast rules", but there are guidelines that say that
certain practices are better than others. Today for example, I discovered
that at Olin's place of work, they use whiteboards, and keep notes by taking
digital pictures -- which is exactly what we do at my job. Are there any
disadvantages to using whiteboards? What "tradeoffs" are there -- do you see
*any* disadvantages to this design practice?

Naming variables/function names in a meaningful way, what's wrong with that?

What's wrong with the rule that states you should avoid "magic" numbers? Or
that you should keep your functions and modules cohesive, and loosely
coupled?

You could say that this stuff is all basic, but can you tell me why we keep
seeing the same mistakes made over and over again, by people who should know
better?

If you haven't yet read "Code Complete", I strongly recommend it. A set of
rules of thumb, and intelligent observations about what works best in the
real world is a lot more useful than implying that every project is
different and you have to figure it out from scratch.

Vitaliy


2009\01\31@175030 by Vitaliy

flavicon
face
Gerhard Fiedler
[snip]
>> - Only the bare minimum of documentation was created, most of it of
>> the "sketch on a napkin" type.
>
> Of course. To do it right, you always do the minimum required (in
> engineering, at least). Everything beyond the required minimum is
> ballast. But the problem is that the minimum required varies
> considerably with the type of project. There are programs where what
> they do, in principle, can be conveyed in a fifteen minute conversation.
> There are others that are so complex that you need a few people working
> on it for a year to gather what the program should do. If they don't
> document what they did during that time, it's lost, and if they do, it's
> a huge amount of documentation. And before they do this, nobody has a
> clue about the scope of the work, so it's not possible to even talk
> about a reasonable contract.

I no longer believe in the magic of documentation, after we spent close to
six man-months and ended up with nothing but a pile of paper.

There is no such thing as perfect communication. It's not my idea, but I
fully subscribe to it. 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
own.

The implication is that you shouldn't fixate on documentation, but instead
find efficient ways to communicate the ideas.


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


>> - Sketching out the design on a whiteboard.
>
> Is often helpful. I like drawings, and I don't have a problem of being
> shown wrong in front of a group. 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.

Hm, I don't know about that. Active participation can be defined as
listening and watching other team members discuss the design. 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.


>> - Refactoring is the way to keep code maintainable, and is usually
>> what I resort to when I dig myself into a hole
>
> 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. 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.

It's not black and white either: early refactoring is less expensive than
late refactoring.


>> - Object Oriented design, which is even possible in C
>
> I don't buy that this is important for success of programming projects
> in general. It's possible, but I think whether it's helpful depends a
> lot on the specific problem.

The fundamental difference b/w procedural programming and OOP, is that OOP
creates an additional layer of abstraction, and helps manage complexity. For
projects with a  low level of complexity, it may not be necessary.


>> I would love to hear what tools/techniques/practices other people find
>> useful in their work.
>
> I tried to convey this in my previous messages... Be flexible, look at
> every aspect of the situation, get to know the people involved (this
> includes you!) and their strengths and weaknesses, how they work and
> what they need, like and dislike, and /adapt/. No matter whether a
> technique is "Agile" or not... if it works in a given situation, it's
> the way to go.

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


Vitaliy

2009\01\31@180804 by olin piclist

face picon face
Vitaliy wrote:
> Well then it's pointless to continue this conversation, isn't it?
> Anything goes, develop your software any way you like, no one way is
> better any other way.

There are certainly some ways that are bad most or all of the time.  There
isn't the One Good Way though.  This depends on the project, people,
customer, facilities, manager, and lots of other stuff too complicated to
make rules about.

> I sense a double standard, however. Both of you (Gerhard and Olin) at
> one time or another advocated (very forcefully at times) a certain
> way of programming, or a design practice.

I thought we were talking about higher level software development practises,
not details like putting constants in-line, at the top of a file, or in a
include file.

> "There are no hard and fast rules", but there are guidelines that say
> that certain practices are better than others. Today for example, I
> discovered that at Olin's place of work, they use whiteboards, and
> keep notes by taking digital pictures

On that day for that project.

> do you see *any* disadvantages to this design practice?

Sure.  First, it's not a design practice but a project management practice.
In this case everybody envolved got together to figure out what was left to
do, how much, and who needed to do it.  This was done interactively with
everyone, including the customer, present.  It was done not only to get a
idea of the work left, but also to give the customer a sense of where things
were at and buy-in from everyone present.  It was logical to write this down
on the whiteboard as the discussion progressed.  Various things were erased,
rewritten, added, deleted, etc as the discussion progressed.

As for disadvantages, some people may not want to speak up in a meeting as
apposed to when you ask them one on one, or they may be afraid to give the
honest answer instead of what they think you or the customer want to hear.
For some people its a distraction to be bothered with stuff that isn't their
problem and they don't care about.  To some customers, this would look Micky
Mouse.  A lot of collective time was also spent.  There are certainly other
ways to manage a project, each with their own advantages and disadvantages.

I guess my main point is that project management style needs to be flexible
for the particulars at hand.  Gee, maybe it'll be more believable if it were
called Agile Management or something.  How about "Fleximent"?  Does that
sound new-fangled drink-the-grape-coolaid good enough?


********************************************************************
Embed Inc, Littleton Massachusetts, http://www.embedinc.com/products
(978) 742-9014.  Gold level PIC consultants since 2000.

2009\01\31@182755 by Alan B. Pearce

face picon face
>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...
>;-)

But from what you have been writing, it seems to me you have pretty well got
that information too. Everyone has got it through experience and 'common
sense', and from what you have been writing, it becomes evident that you
have as well. Or is it that you have now got a project that has expanded
beyond your experience and is threatening to go belly up in some way (may
well not be through the fault of your company - your client wants something
rather different with change in economic situation maybe).

I don't think there is a 'silver bullet' for this, as you pointed out
earlier today when you had Olin and Gerhard on about how they have in the
past advocated very strongly for what you saw as a paradigm, and that now
they were saying there is no 'one way'. I think they were saying that there
are definite wrong ways to do some things and definite right ways to do some
things, but the rights and wrongs depend on the project size, and the way
things are done may need fine tuning as a project proceeds.

2009\01\31@221840 by apptech

face
flavicon
face
>> "There are no hard and fast rules", but there are guidelines that say
>> that certain practices are better than others. Today for example, I
>> discovered that at Olin's place of work, they use whiteboards, and
>> keep notes by taking digital pictures
>
> On that day for that project.
>
>> do you see *any* disadvantages to this design practice?
>
> Sure.  First, it's not a design practice but a project management
> practice.

Somewhat peripheral, but when 'away' I favour the use of whiteboards for
group discussion and I take photos. I try to make sure everything covered
gets at least a whiteboard reference. Not just a useful aide memoire for me
but others know that I have the record. While it is not usually necessary to
use such for backup when a point is in questin, the ability to effectively
jump to that point in time and demonstrate a snapshot of the chronological
development of the discussion and the key points covered can be utterly
invaluable. This doesn't replace more formal notes and records (or
shouldn't) but is vvv useful.

And the grandchildren (none of whom yet exist) can pore over the pictures in
years to come and decide whether they refer to cans of Jolt required to
finish a project. (In one meeting I drew a sketch of a tiger with the
(female) Chinese design engineer flying along behind holding its tail. The
"got a tiger by the tail" metaphor seemed to be unknown until then. Later
allusion to the picture was far more useful than dry references to the
merits of keeping projects under control rather than later trying to get
them back in control. Not that it helped in the end :-).



        Russell

2009\01\31@233311 by William \Chops\ Westfield

face picon face

On Jan 31, 2009, at 2:49 PM, Vitaliy wrote:

> There is no such thing as perfect communication.

I think the problem with many development methodologies is that they  
fail to scale well.  I've had some of my most productive moments  
sharing a bull-pen like room with 1 to 6 other engineers, but I can't  
imagine enjoying sharing an "open space" with 20-odd people, and I  
sure don't see how to scale "good communications" to projects  
involving more than 100 people.

(At one time we had a policy of seating SW engineers in cubes next to  
HW engineeers, and that accomplished some good things when most HW  
efforts involved one or two HW engineers and most SW efforts involved  
one SW engineer.  But it pretty much died when the projects got big  
enough to involve more than 3 of each...  Sigh.)

BillW


'[TECH] Positive experiences with software developm'
2009\02\01@091126 by Gerhard Fiedler
picon face
Vitaliy wrote:

>>> - Only the bare minimum of documentation was created, most of it of
>>> the "sketch on a napkin" type.
>>
>> Of course. To do it right, you always do the minimum required (in
>> engineering, at least). Everything beyond the required minimum is
>> ballast. But the problem is that the minimum required varies
>> considerably with the type of project. There are programs where what
>> they do, in principle, can be conveyed in a fifteen minute
>> conversation. There are others that are so complex that you need a
>> few people working on it for a year to gather what the program
>> should do. If they don't document what they did during that time,
>> it's lost, and if they do, it's a huge amount of documentation. And
>> before they do this, nobody has a clue about the scope of the work,
>> so it's not possible to even talk about a reasonable contract.
>
> I no longer believe in the magic of documentation, after we spent
> close to six man-months and ended up with nothing but a pile of
> paper.

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

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

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

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

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
this?

> 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
"something else".

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

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

Gerhard

2009\02\01@181303 by Vitaliy

flavicon
face
William "Chops" Westfield wrote:
>> There is no such thing as perfect communication.
>
> I think the problem with many development methodologies is that they
> fail to scale well.  I've had some of my most productive moments
> sharing a bull-pen like room with 1 to 6 other engineers, but I can't
> imagine enjoying sharing an "open space" with 20-odd people, and I
> sure don't see how to scale "good communications" to projects
> involving more than 100 people.
>
> (At one time we had a policy of seating SW engineers in cubes next to
> HW engineeers, and that accomplished some good things when most HW
> efforts involved one or two HW engineers and most SW efforts involved
> one SW engineer.  But it pretty much died when the projects got big
> enough to involve more than 3 of each...  Sigh.)

I agree there needs to be a balance. For example, McConnell recommends using
pair programming only for the difficult parts of the code, and discourages
its use for routine programming.

However, the agile concept of small teams can definitely be scaled (it's
been done in the real world). I already explained it in the "agile" thread,
but the way it works is, a small "top-level" team is formed, consisting of
delegates (product owners), one from each lower-level team. If more people
are involved, the process is repeated.

This is similar to traditional environments where you have a manager (or a
team lead), the difference being that within each agile team, communication
barriers are reduced.

Vitaliy

2009\02\01@182841 by Vitaliy

flavicon
face
Alan B. Pearce wrote:
> >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...
>>;-)
>
> But from what you have been writing, it seems to me you have pretty well
> got
> that information too. Everyone has got it through experience and 'common
> sense', and from what you have been writing, it becomes evident that you
> have as well.

I don't know Alan, I am pretty stubborn and sometimes keep beating my head
against the same wall, until someone points out that there is a better way.
A lot of things that made me more productive, came from books and stuff I
read on the internet (PICList plays a huge part, too).

I guess that maybe what I'm after, is validating the ideas I have, as much
as learning new thigns. The fact that I have a strong opinion about
something, doesn't mean I won't change it when presented with compelling
evidence.


> Or is it that you have now got a project that has expanded
> beyond your experience and is threatening to go belly up in some way (may
> well not be through the fault of your company - your client wants
> something
> rather different with change in economic situation maybe).

Not yet, but I'd like to be prepared. The more I learn, the more I don't
know -- right?  Tapping several thousand years of collective experience
might help me make fewer mistakes. And I'd be happy to share what I learned
from my mistakes.


> I don't think there is a 'silver bullet' for this, as you pointed out
> earlier today when you had Olin and Gerhard on about how they have in the
> past advocated very strongly for what you saw as a paradigm, and that now
> they were saying there is no 'one way'. I think they were saying that
> there
> are definite wrong ways to do some things and definite right ways to do
> some
> things, but the rights and wrongs depend on the project size, and the way
> things are done may need fine tuning as a project proceeds.

Sure, let's talk about these factors, too.

Vitaliy

2009\02\01@183927 by Vitaliy

flavicon
face
Olin Lathrop wrote:
> There are certainly some ways that are bad most or all of the time.  There
> isn't the One Good Way though.  This depends on the project, people,
> customer, facilities, manager, and lots of other stuff too complicated to
> make rules about.

How about just describing a project that either went well, or was a
failure -- and trying to analyze what were the contributing factors? Isn't
this what learning is really about?


>> I sense a double standard, however. Both of you (Gerhard and Olin) at
>> one time or another advocated (very forcefully at times) a certain
>> way of programming, or a design practice.
>
> I thought we were talking about higher level software development
> practises,
> not details like putting constants in-line, at the top of a file, or in a
> include file.

Sometimes a small change can make a big difference. So no, I don't think
limiting the scope of discussion to higher leve development practices is a
good idea.


>> "There are no hard and fast rules", but there are guidelines that say
>> that certain practices are better than others. Today for example, I
>> discovered that at Olin's place of work, they use whiteboards, and
>> keep notes by taking digital pictures
>
> On that day for that project.

Do you think it worked well? Would you use it again? Why, or why not?


{Quote hidden}

That's how I've seen it used, and how we use it at work. I almost forgot,
that's another great thing about a whiteboard -- erasing stuff is very easy
(easier than erasing something written with a pencil).


{Quote hidden}

I hear you. And yet in my experience, I haven't encountered these
difficulties. We usually spend maybe one or two hours per week
"whiteboarding" -- and it pays for itself many times over.


> I guess my main point is that project management style needs to be
> flexible
> for the particulars at hand.  Gee, maybe it'll be more believable if it
> were
> called Agile Management or something.  How about "Fleximent"?  Does that
> sound new-fangled drink-the-grape-coolaid good enough?

A rose by any other name... :-)

Vitaliy

2009\02\01@184253 by Vitaliy

flavicon
face
apptech wrote:
> In one meeting I drew a sketch of a tiger with the
> (female) Chinese design engineer flying along behind holding its tail. The
> "got a tiger by the tail" metaphor seemed to be unknown until then. Later
> allusion to the picture was far more useful than dry references to the
> merits of keeping projects under control rather than later trying to get
> them back in control. Not that it helped in the end :-).

Russell, on behalf of the citizenry, I insist that you share the sketch. :-)

Vitaliy

2009\02\02@001007 by Vitaliy

flavicon
face
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
programmers.

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


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

http://www.agilemodeling.com/essays/communication.htm

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


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

Yes.


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


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

Vitaliy

2009\02\02@045110 by Alan B. Pearce

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

I guess the thing here is to limit the capabilities of the person who is
unfamiliar with the project - to someone who would have the necessary
knowledge and experience to have been involved in the project previously.
I.e. you are not documenting the project so that a fresh apprentice can
understand it - which is what it sounds like was happening on the one where
you got overwhelmed by paper.

2009\02\02@051810 by Vitaliy

flavicon
face
"Alan B. Pearce" wrote:
> >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.
>
> I guess the thing here is to limit the capabilities of the person who is
> unfamiliar with the project - to someone who would have the necessary
> knowledge and experience to have been involved in the project previously.
> I.e. you are not documenting the project so that a fresh apprentice can
> understand it - which is what it sounds like was happening on the one
> where
> you got overwhelmed by paper.

While your guess is true in part, I think there is a more fundamental
problem. The guy we contracted was an expert in the field, completed a
similar project previously, and even published the results. I'm sure he was
more than capable of successfully completing the project, and that our
methodology was what killed it.

There are several problems with software documentation:

1. It's not interactive. You can't predict which parts will not be clear to
the person reading the docs, and it's likely that different people would be
confused by different things.

2. The natural response to try to alleviate #1 is to produce increasignly
detailed, comprehensive specifications. Lots of extra work, most of it
unnecessary, and counter-productive in terms of its usefulness to the person
it's intended for (imagine trying to find something in a 40,000 page spec).

3. It can quickly get out of sync with the code (and often does).

Possible ways to keep the spec from reaching unmanageable size:

- Try to keep programmer turnover to a minimum, and ensure a smooth
transition (let new programmers assimilate before the old ones leave).
- Write self-documenting code

FWIW,

Vitaliy

2009\02\04@074352 by Gerhard Fiedler

picon face
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
documented.

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

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

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

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

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.

Gerhard

2009\02\17@031714 by Vitaliy

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

Vitaliy

2009\02\17@074343 by Gerhard Fiedler

picon face
Vitaliy wrote:

> Gerhard Fiedler wrote:
>>> 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.

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

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

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

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

Gerhard

2009\02\17@085211 by Lee Jones

flavicon
face
I may well regret throwing fuel on the fire that is keeping this
thread alive...


{Quote hidden}

I'm uncomfortable that both sides keep arguing about the single word

   documentation

when it covers such a wide range of information from requirements &
specifications to user manuals.  Trying to write all of it, a priori,
and "casting it in stone" _is_ an impossible task.  But writing down
none of it in advance is a practical impossibility too.

But the vast majority of my clients over many years will _NOT_
sign off on a contract proposal until they know what it will cost
and I won't quote a fixed price until I know what I must deliver.
That mandates a requirements & specifications document up front.

Frequently it appears the business people who sign the checks are
more concerned with the final cost than what gets delivered (within
reasonable limits).  I expect I'd be laughed out of the room if I
proposed that they specify "just enough" to work for two weeks of
work -- and they pay my for that work -- with no up-front guarantee
of what the final product would look like.  That's the reality of
the marketplace that I work within.

And it doesn't have to be cast in stone.  In almost every project
that I have ever worked on, the requirements agreement was revised
one or more times during the construction process.  It does not
matter if it's software, cabling, or a building -- the change order
process (with fees for each change) is well know and understood.

I have had a couple clients who could live with the Agile purist
method -- but they are very rare and it took years to build a
relationship first.


>>> { 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've frequently had requirements documents where certain sections
are "TBD".  They get filled in during the project.  Sometimes on
an as needed basis; sometimes after certain milestones are met.

Nothing is "set in stone" until the final check is cashed and
the client doesn't sue you. :-)



In reference to Brook's Mythical Man-Month stating that the first
version of software will be thrown away...

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

It strikes me that an Agile purist's refactoring of code can be
considered to be "throwing away" the first version of software
in a piece-wise fashion.  At the end of the project, an Agile
program team has written the second version -- one bit at a time.

It's very difficult for any programmer to fully understand all the
application space constraints -- particulary the "unwritten rules"
or "corporate memory" that the workers develop over years/decades
through experience -- until the programmer(s) have been immersed in
the project for a while.  That alone makes it almost a given that
the requirements (as implemented in the software) will change even
if the "requirements spec" is never updated.

                                               Lee Jones

2009\02\18@043715 by Vitaliy

flavicon
face
Gerhard Fiedler wrote:
> Remember, it's you who's saying that there can't be useful
> documentation.

Just for the record: I never said that, nor could I.


2009\02\18@085734 by Gerhard Fiedler

picon face
Vitaliy wrote:

> Gerhard Fiedler wrote:
>> Remember, it's you who's saying that there can't be useful
>> documentation.
>
> Just for the record: I never said that, nor could I.

Not the same, but whenever I say that documentation can be useful (not
that all documentation ever created is useful), you find something
against this affirmation.


You:
> The implication is that you shouldn't fixate on documentation, but
> instead find efficient ways to communicate the ideas.

You shouldn't fixate on anything (not even on Agile :), so that's a
commonplace. But good documentation /is/ an efficient way to communicate
ideas -- IMO much more efficient than video. IMO video and audio are
among the most inefficient means of documentation -- quite different to
the Agile paper you cited earlier. I almost never listen to podcasts;
what they say in 30 minutes I generally can read up on in 10 minutes or
less; sometimes much less.


You about documentation:
> lots of useless paper

That is /bad/ documentation. Bad code is lots of useless bits; such
statements don't get us anywhere. I thought we were talking about /good/
code -- and /good/ documentation.


You:
> I am especially strongly against creating detailed project
> specifications early in the development.

If the details are known without making assumptions -- what's wrong with
documenting them? Why would you deliberately want to not know something
that is known?


You:
> Paper is about the worst form of communication there is.

This statement was made in the context of an Agile article that puts
"paper" and "electronic documents" like PDFs in the same category. I
still didn't get an answer to the question why you think that PDFs are
an efficient means to communicate the specs of a chip, but not the specs
of software.


Me: "when documenting, don't make assumptions."
You: "Impossible".

This basically seems to say that when you go into a project, you know
/nothing/ at all. Because if you know something, you can document it
without making assumptions. That's one purpose of documentations: get
rid of assumptions. Help the programmers so they don't have to make
assumptions.


You:
> If a procedure places more value on documentation than on working
> code, I will scrap it -- because it contradicts a principle which I
> consider sound.

If documentation is what you need, what's the problem? Your statement
makes only sense if you assume that you never need documentation. Which
gets us back to the initial exchange of this email: if you think there
can be useful documentation, why would you scrap a procedure that places
value on creating this (supposedly useful) documentation? Or conversely,
if you scrap every procedure that puts value on documentation, how do
you think you get good documentation? Without placing any focus on it?
Creating documentation and writing code are two different things, and
they generally need different procedures (and also generally different
people are good at it, so they are naturally separate tasks).

If you want /good/ documentation, you need to focus on it. If you don't,
chances are your documentation won't be good and standing for itself.
(For example, pictures of whiteboards can be good, but they generally
don't stand for themselves, without additional context and explanation.)

Gerhard

2009\02\24@031638 by Vitaliy

flavicon
face
Gerhard Fiedler wrote:
>> Gerhard Fiedler wrote:
>>> Remember, it's you who's saying that there can't be useful
>>> documentation.
>>
>> Just for the record: I never said that, nor could I.
>
> Not the same, but whenever I say that documentation can be useful (not
> that all documentation ever created is useful), you find something
> against this affirmation.

You should consider starting your sentences attacking me, with "It *seems*
that..." :-)


> You about documentation:
>> lots of useless paper

Sorry, but I think it is intellectually dishonest to take my comments out of
context like that.


> You:
>> I am especially strongly against creating detailed project
>> specifications early in the development.
>
> If the details are known without making assumptions -- what's wrong with
> documenting them? Why would you deliberately want to not know something
> that is known?

One reason is that you don't know if you will ever use this information. You
can barely predict what will happen next week, why try to predict what will
happen six months, or a year from now?


> You:
>> Paper is about the worst form of communication there is.
>
> This statement was made in the context of an Agile article that puts
> "paper" and "electronic documents" like PDFs in the same category. I
> still didn't get an answer to the question why you think that PDFs are
> an efficient means to communicate the specs of a chip, but not the specs
> of software.

Gerhard, you need to put this in context. If you and I worked on the same
project, and you had a choice between communicating using paper (writing
notes to each other), or talking face-to-face -- would it not be a
no-brainer?

If you had a choice, would it not be better if you had the engineers who
designed your PIC, in the same room with you?

Paper documentation has its place, it's just not as effective as other means
for communication among developers.

Please, stop trying to make me look like a docuphobe.


> Me: "when documenting, don't make assumptions."
> You: "Impossible".
>
> This basically seems to say that when you go into a project, you know
> /nothing/ at all.

Appearances are deceiving. :)  The problem is, some of the things you think
you know, you don't know. And if you don't know which things that you think
you know, you don't know -- how can you know not to make assumptions about
the things you don't know (since we established that you don't know which
things that you think you know, you don't know)?


> Because if you know something, you can document it
> without making assumptions. That's one purpose of documentations: get
> rid of assumptions. Help the programmers so they don't have to make
> assumptions.

Can you tell me with a straight face, that when you are writing specs for a
project (which, by definition, involves a high degree of uncertainty) you
never make assumptions? And you never had to go back, and make changes?


> You:
>> If a procedure places more value on documentation than on working
>> code, I will scrap it -- because it contradicts a principle which I
>> consider sound.
>
> If documentation is what you need, what's the problem?

You can't eat it, you can't use it to control a car engine, you can't use it
to supervise industrial processes. What is it good for, in and of itself? I
suppose you could use it as kindling, or to make origami, but there exist
more suitable and cheaper alternatives.


> Your statement
> makes only sense if you assume that you never need documentation.

No, it makes sense if you assume that the value is in the project
objectives, and documentation is useful only as long as it helps achieve
these objectives.


> Which
> gets us back to the initial exchange of this email: if you think there
> can be useful documentation, why would you scrap a procedure that places
> value on creating this (supposedly useful) documentation? Or conversely,
> if you scrap every procedure that puts value on documentation, how do
> you think you get good documentation? Without placing any focus on it?
> Creating documentation and writing code are two different things, and
> they generally need different procedures (and also generally different
> people are good at it, so they are naturally separate tasks).

You are fighting windmills. I'm tired of saying that I am *in favor* of
documentation. What I am against, is wasting time on creating and
maintaining unnecessary documentation.

Unnecessary documentation is produced when people try to document the
project upfront (following the prescriptions of the waterfall approach).


> If you want /good/ documentation, you need to focus on it. If you don't,
> chances are your documentation won't be good and standing for itself.
> (For example, pictures of whiteboards can be good, but they generally
> don't stand for themselves, without additional context and explanation.)

Sometimes a snapshot of a drawing on a whiteboard, or notes on a napkin, is
all you need. Sometimes you need a more formal document. Spend as much time
on documentation, as necessary -- but not more.

Vitaliy

2009\02\24@110035 by Gerhard Fiedler

picon face
Vitaliy wrote:

>> You:
>>> Paper is about the worst form of communication there is.
>>
>> This statement was made in the context of an Agile article that puts
>> "paper" and "electronic documents" like PDFs in the same category. I
>> still didn't get an answer to the question why you think that PDFs
>> are an efficient means to communicate the specs of a chip, but not
>> the specs of software.
>
> Gerhard, you need to put this in context. If you and I worked on the
> same project, and you had a choice between communicating using paper
> (writing notes to each other), or talking face-to-face -- would it
> not be a no-brainer?

No, it would not be. If we worked on a project, we had the choice -- nor
"if" there. But the choices have costs attached to them. The cost of
talking to you face-to-face would be quite big. In this case, like in
others, figuring out where the most efficient mix of communication is
depends a lot on the involved people, the project, and so on.

> If you had a choice, would it not be better if you had the engineers
> who designed your PIC, in the same room with you?

You said it: "if you had a choice". Project management is not about
dreaming what would be if I had a choice, but about making the project
work as well as possible with what I have -- considering the benefits
and costs of each possible choice.

> Paper documentation has its place, it's just not as effective as other
> means for communication among developers.

It can be more effective, depending on the situation. Efficiency is not
about an "if everything were perfect" situation, it is about the
real-world project situation. Watching videos about software
architecture is not efficient, at least not for me.


>> Me: "when documenting, don't make assumptions."
>> You: "Impossible".
>>
>> This basically seems to say that when you go into a project, you know
>> /nothing/ at all.
>
> Appearances are deceiving. :)  The problem is, some of the things you
> think you know, you don't know.

This is something that comes with experience: less "thinking that you
know" and more "knowing", and more ability to discern between the two.
It's an important skill.

> how can you know not to make assumptions about the things you don't
> know (since we established that you don't know which things that you
> think you know, you don't know)?

Documenting what you think you know and learning from it is a good means
to progress on the path towards less "thinking that you know" and more
"knowing".


>> Because if you know something, you can document it without making
>> assumptions. That's one purpose of documentations: get rid of
>> assumptions. Help the programmers so they don't have to make
>> assumptions.
>
> Can you tell me with a straight face, that when you are writing specs
> for a project (which, by definition, involves a high degree of
> uncertainty) you never make assumptions? And you never had to go
> back, and make changes?

I could (I can control my face) but I wouldn't (because there's nothing
in for me). This is besides the point. It's not about "never" or
"always", it's about "reasonable", "more suitable" and "more efficient".


>> You:
>>> If a procedure places more value on documentation than on working
>>> code, I will scrap it -- because it contradicts a principle which I
>>> consider sound.
>>
>> If documentation is what you need, what's the problem?
>
> You can't eat it,

Try to eat software written with Agile methods sometime. May be an eye
opener.

> What is it good for, in and of itself?

You can use it to write software. Good documentation can help a lot in
writing.

> I suppose you could use it as kindling, or to make origami, but there
> exist more suitable and cheaper alternatives.

Probably. If Origami is your thing, then you definitely shouldn't worry
much about documentation. You should go to Japan and stay with a master
for a while.


>> Your statement makes only sense if you assume that you never need
>> documentation.
>
> No, it makes sense if you assume that the value is in the project
> objectives, and documentation is useful only as long as it helps
> achieve these objectives.

Exactly. (Same goes for software.) So what's wrong with creating
documentation if it does? And what's wrong with having procedures that
help doing this, if it does? (Same goes for software.)


> What I am against, is wasting time on creating and maintaining
> unnecessary documentation.

Nobody ever made a case for creating or maintaining unnecessary
documentation.

> Unnecessary documentation is produced when people try to document the
> project upfront (following the prescriptions of the waterfall
> approach).

This is what you think. It is not what some other people think. It is
definitely not a fact. Besides, not every documentation created before
the software is created "following the prescriptions of the waterfall
approach". This focus on the waterfall approach seems to be your thing.
Nobody else in this discussion seems to think of it.

> Sometimes a snapshot of a drawing on a whiteboard, or notes on a
> napkin, is all you need. Sometimes you need a more formal document.
> Spend as much time on documentation, as necessary -- but not more.

This is what I've been saying all along. And what and how much is
necessary depends a lot on the specific project -- and is a judgment
call of the project manager (and possibly others).

So where's it that you think I'm wrong?

Gerhard

More... (looser matching)
- Last day of these posts
- In 2009 , 2010 only
- Today
- New search...