Why do we spend time on documents?

[banshee858]

I wonder what need is being filled, both by writing the documents
and by not writing tests/code. Could you have a non-judgemental
discussion with one of the people who practice documentation-first
and find out what their conscious purposes and principles are?

I had the conversation you suggested and the reason why we are
creating the documents is so we can have documentation - to provide
other people who will look at the software later a way to understand
what we were thinking when the software was implemented. I
specifically asked if the documents were there to help us understand
the "detailed design" and the answer was no.

Carlton

[Ron Jeffries]

Post by banshee858

I wonder what need is being filled, both by writing the documents
and by not writing tests/code. Could you have a non-judgemental
discussion with one of the people who practice documentation-first
and find out what their conscious purposes and principles are?

I had the conversation you suggested and the reason why we are
creating the documents is so we can have documentation - to provide
other people who will look at the software later a way to understand
what we were thinking when the software was implemented. I
specifically asked if the documents were there to help us understand
the "detailed design" and the answer was no.

Would we like these people to understand how the software IS
implemented, or how we imagined it would be before we started? If
the latter ... what aspects of that do they need to understand? I'm
thinking the answer might limit what we write.

Ron Jeffries
www.XProgramming.com
The practices are not the knowing: they are a path to the knowing.

[BenAveling]

Documenting your project, or your process, is like going shopping with a
list of things you need. It doesn't force you to buy those things if
you see something better. It does help you come home with a bag of
things that are more likely to meet your needs for the rest of the week.

BDUF says that since you live a long way from the shop, it's worth
spending the time to do a shopping list. Because the shop might be out
of some things, it's a good idea to consult with [s]he who must be kept
happy before going to the shop and to have a plan that covers all
contingencies. Agile says why don't we just move next door to the shop?

I'm currently investing a little of my time in contributing to the
department's process documents. I'm trying to get us to document much
more of the 'what we do'.

Let me explain why.

There are certain corners that should not be cut. We tend to cut them.

Often, we do this knowingly, because we can't see any better options.
We includes me.

Why, you ask?

Think of a race car. Now, driving through the ditch by the side of the
road is bad. But if you've come off the track, it's a risk you may
have to take.

The hard question is not "do we drive through the ditch again?". It is,
or it should be, "how come we are off the track again?"

Often, we don't know. Part of the reason for that is much of we do
happens via undocumented pathways. People just find ways to make things
work.

To return to the metaphor, we ran out of track, so we went
cross-country, and we thought we would pick up the track again, but now
it seems that it's on the other side of that ditch, so either we go back
a million miles, or we go though the ditch. And we dropped the spare
fuel can the last time we went through a ditch so we don't actually have
the fuel to backtrack. On the other hand, we don't exactly know where
that path goes either, so maybe we should just keep going cross country.

Documentation is an aid to thinking, not a replacement for thinking.

Having a list of things that have to be done can be used to disempower
engineers. 'Go do this. Now do this.'

But, it can also be empowering. 'Sir, the process says that I need to
give this information to X. If I cut that corner, then X cannot ...'

If I have a map of the whole territory, I have some expectation of
arriving.

If the map turns out to be wrong, I have an understanding of what I can
do to get back on track, including the option of finding a new track.

Even if I chose the worst possible path, I can do better next time, if I
record the path I took.

Once I've managed to follow the map a few times I won't need the map any
more. I'll know a route that gets me where I want to go.

But if I struggle and guess and fumble through a different path each
time, and if I don't know which path I took, then I don't get feedback
on which of my many guesses were right or wrong and I'll probably never
learn.

When we aren't getting the outcomes we want, understanding the
difference between what actually do and what we think we should do is
valuable.

When things are left unsaid then we can believe different things and
have gaps in our knowledge and not realise that there is a problem.
When we have to say 'it is thus' such gaps become very obvious.

Regards, Ben A

[Turpin, Jay]

It really matters who is going to the store to do the shopping. If it's
the wife (the expert shopper in most families), a shopping list with a
few items listed on it will do fine. She is able to intelligently make
substitutions if a particular item is unavailable and buy additional
things if an unplanned item is on sale.

However, if I am going to the store, I will need a list with much
greater detail. Which brand of spaghetti sauce should I get? What if
they are out of lima beans? Can black beans be substituted? My wife can
only document some of the detail. She is unaware of the depth of my
ignorance in these matters. I will invariably make mistakes.

Agile development believes in shopping lists. But it also believes in
bringing our wives to the store with us. Or at least a cell phone, so we
can call and clarify the requirements when we run off the road.

Regards,
Jay Turpin
Intel Corporation
"Cowardice asks the question - is it safe? Expediency asks the question
- is it politic? Vanity asks the question - is it popular? But
conscience asks the question - is it right? And there comes a time when
one must take a position that is neither safe, nor politic, nor popular;
but one must take it BECAUSE it is right." - Dr. Martin Luther King

-----Original Message-----
From: xpbookdiscussiongroup-***@public.gmane.org
[mailto:xpbookdiscussiongroup-***@public.gmane.org] On Behalf Of BenAveling
Sent: Saturday, April 23, 2005 4:49 PM
To: xpbookdiscussiongroup-***@public.gmane.org
Subject: Re: [xpe2e] Why do we spend time on documents?



Documenting your project, or your process, is like going shopping with a
list of things you need. It doesn't force you to buy those things if
you see something better. It does help you come home with a bag of
things that are more likely to meet your needs for the rest of the week.

BDUF says that since you live a long way from the shop, it's worth
spending the time to do a shopping list. Because the shop might be out
of some things, it's a good idea to consult with [s]he who must be kept
happy before going to the shop and to have a plan that covers all
contingencies. Agile says why don't we just move next door to the shop?

I'm currently investing a little of my time in contributing to the
department's process documents. I'm trying to get us to document much
more of the 'what we do'.

Let me explain why.

There are certain corners that should not be cut. We tend to cut them.

Often, we do this knowingly, because we can't see any better options.
We includes me.

Why, you ask?

Think of a race car. Now, driving through the ditch by the side of the
road is bad. But if you've come off the track, it's a risk you may
have to take.

The hard question is not "do we drive through the ditch again?". It is,
or it should be, "how come we are off the track again?"

Often, we don't know. Part of the reason for that is much of we do
happens via undocumented pathways. People just find ways to make things
work.

To return to the metaphor, we ran out of track, so we went
cross-country, and we thought we would pick up the track again, but now
it seems that it's on the other side of that ditch, so either we go back
a million miles, or we go though the ditch. And we dropped the spare
fuel can the last time we went through a ditch so we don't actually have
the fuel to backtrack. On the other hand, we don't exactly know where
that path goes either, so maybe we should just keep going cross country.

Documentation is an aid to thinking, not a replacement for thinking.

Having a list of things that have to be done can be used to disempower
engineers. 'Go do this. Now do this.'

But, it can also be empowering. 'Sir, the process says that I need to
give this information to X. If I cut that corner, then X cannot ...'

If I have a map of the whole territory, I have some expectation of
arriving.

If the map turns out to be wrong, I have an understanding of what I can
do to get back on track, including the option of finding a new track.

Even if I chose the worst possible path, I can do better next time, if I
record the path I took.

Once I've managed to follow the map a few times I won't need the map any
more. I'll know a route that gets me where I want to go.

But if I struggle and guess and fumble through a different path each
time, and if I don't know which path I took, then I don't get feedback
on which of my many guesses were right or wrong and I'll probably never
learn.

When we aren't getting the outcomes we want, understanding the
difference between what actually do and what we think we should do is
valuable.

When things are left unsaid then we can believe different things and
have gaps in our knowledge and not realise that there is a problem.
When we have to say 'it is thus' such gaps become very obvious.

Regards, Ben A




Yahoo! Groups Links

[Ron Jeffries]

Nice metaphor, Jay. Be assured that I'm going to steal it. With
attribution, most times.

Thanks,

Ron Jeffries
www.XProgramming.com
Will Turner: This is either madness or brilliance.
Captain Jack Sparrow: It's remarkable how often those two traits coincide.

Post by Turpin, Jay
It really matters who is going to the store to do the shopping. If it's
the wife (the expert shopper in most families), a shopping list with a
few items listed on it will do fine. She is able to intelligently make
substitutions if a particular item is unavailable and buy additional
things if an unplanned item is on sale.
However, if I am going to the store, I will need a list with much
greater detail. Which brand of spaghetti sauce should I get? What if
they are out of lima beans? Can black beans be substituted? My wife can
only document some of the detail. She is unaware of the depth of my
ignorance in these matters. I will invariably make mistakes.
Agile development believes in shopping lists. But it also believes in
bringing our wives to the store with us. Or at least a cell phone, so we
can call and clarify the requirements when we run off the road.

[John Goodsen]

Nice analogy, Jay!

Post by Turpin, Jay
It really matters who is going to the store to do the shopping. If it's
the wife (the expert shopper in most families), a shopping list with a
few items listed on it will do fine. She is able to intelligently make
substitutions if a particular item is unavailable and buy additional
things if an unplanned item is on sale.
However, if I am going to the store, I will need a list with much
greater detail. Which brand of spaghetti sauce should I get? What if
they are out of lima beans? Can black beans be substituted? My wife can
only document some of the detail. She is unaware of the depth of my
ignorance in these matters. I will invariably make mistakes.
Agile development believes in shopping lists. But it also believes in
bringing our wives to the store with us. Or at least a cell phone, so we
can call and clarify the requirements when we run off the road.
Regards,
Jay Turpin
Intel Corporation
"Cowardice asks the question - is it safe? Expediency asks the question
- is it politic? Vanity asks the question - is it popular? But
conscience asks the question - is it right? And there comes a time when
one must take a position that is neither safe, nor politic, nor popular;
but one must take it BECAUSE it is right." - Dr. Martin Luther King
-----Original Message-----
Sent: Saturday, April 23, 2005 4:49 PM
Subject: Re: [xpe2e] Why do we spend time on documents?
Documenting your project, or your process, is like going shopping with a
list of things you need. It doesn't force you to buy those things if
you see something better. It does help you come home with a bag of
things that are more likely to meet your needs for the rest of the week.
BDUF says that since you live a long way from the shop, it's worth
spending the time to do a shopping list. Because the shop might be out
of some things, it's a good idea to consult with [s]he who must be kept
happy before going to the shop and to have a plan that covers all
contingencies. Agile says why don't we just move next door to the shop?
I'm currently investing a little of my time in contributing to the
department's process documents. I'm trying to get us to document much
more of the 'what we do'.
Let me explain why.
There are certain corners that should not be cut. We tend to cut them.
Often, we do this knowingly, because we can't see any better options.
We includes me.
Why, you ask?
Think of a race car. Now, driving through the ditch by the side of the
road is bad. But if you've come off the track, it's a risk you may
have to take.
The hard question is not "do we drive through the ditch again?". It is,
or it should be, "how come we are off the track again?"
Often, we don't know. Part of the reason for that is much of we do
happens via undocumented pathways. People just find ways to make things
work.
To return to the metaphor, we ran out of track, so we went
cross-country, and we thought we would pick up the track again, but now
it seems that it's on the other side of that ditch, so either we go back
a million miles, or we go though the ditch. And we dropped the spare
fuel can the last time we went through a ditch so we don't actually have
the fuel to backtrack. On the other hand, we don't exactly know where
that path goes either, so maybe we should just keep going cross country.
Documentation is an aid to thinking, not a replacement for thinking.
Having a list of things that have to be done can be used to disempower
engineers. 'Go do this. Now do this.'
But, it can also be empowering. 'Sir, the process says that I need to
give this information to X. If I cut that corner, then X cannot ...'
If I have a map of the whole territory, I have some expectation of
arriving.
If the map turns out to be wrong, I have an understanding of what I can
do to get back on track, including the option of finding a new track.
Even if I chose the worst possible path, I can do better next time, if I
record the path I took.
Once I've managed to follow the map a few times I won't need the map any
more. I'll know a route that gets me where I want to go.
But if I struggle and guess and fumble through a different path each
time, and if I don't know which path I took, then I don't get feedback
on which of my many guesses were right or wrong and I'll probably never
learn.
When we aren't getting the outcomes we want, understanding the
difference between what actually do and what we think we should do is
valuable.
When things are left unsaid then we can believe different things and
have gaps in our knowledge and not realise that there is a problem.
When we have to say 'it is thus' such gaps become very obvious.
Regards, Ben A
Yahoo! Groups Links
Yahoo! Groups Links

----
John Goodsen RADSoft / Better Software Faster
jgoodsen-***@public.gmane.org Extreme Programmer and Coach
http://www.radsoft.com Enterprise Java and .NET Solutions

[Steven Gordon]

To stretch the analogy a bit further, would it ever make sense to file all the shopping lists our wife has given us over the years? Would it make sense to reference this old information the next time we have a question instead of directly asking our wife? If black beans was a suitable substitute in a recipe last year, would it make it safe to assume it is a suitable substitute this week? If $2 was too much to pay for the spaghetti sauce last year, is it too much this year?

I think it would not make sense to file old shopping lists for future reference. Analogously, I believe we should do however much documentation and modeling is necessary to accomplish our current objectives, but once those objective are attained and verified through feedback, persisting most of that working documentation generally creates more longterm overhead and misinformation than it is worth. Any documentation that can be inferred from the tests and the code are redundant, so we should dispose of that working documentation and move on.

Steven Gordon
http://sf.asu.edu/

Post by Turpin, Jay
It really matters who is going to the store to do the shopping. If it's
the wife (the expert shopper in most families), a shopping list with a
few items listed on it will do fine. She is able to intelligently make
substitutions if a particular item is unavailable and buy additional
things if an unplanned item is on sale.
However, if I am going to the store, I will need a list with much
greater detail. Which brand of spaghetti sauce should I get? What if
they are out of lima beans? Can black beans be substituted? My wife can
only document some of the detail. She is unaware of the depth of my
ignorance in these matters. I will invariably make mistakes.
Agile development believes in shopping lists. But it also believes in
bringing our wives to the store with us. Or at least a cell phone, so
we
can call and clarify the requirements when we run off the road.
Regards,
Jay Turpin
Intel Corporation
"Cowardice asks the question - is it safe? Expediency asks the question
- is it politic? Vanity asks the question - is it popular? But
conscience asks the question - is it right? And there comes a time when
one must take a position that is neither safe, nor politic, nor
popular;
but one must take it BECAUSE it is right." - Dr. Martin Luther King
-----Original Message-----
Sent: Saturday, April 23, 2005 4:49 PM
Subject: Re: [xpe2e] Why do we spend time on documents?
Documenting your project, or your process, is like going shopping with
a
list of things you need. It doesn't force you to buy those things if
you see something better. It does help you come home with a bag of
things that are more likely to meet your needs for the rest of the
week.
BDUF says that since you live a long way from the shop, it's worth
spending the time to do a shopping list. Because the shop might be out
of some things, it's a good idea to consult with [s]he who must be kept
happy before going to the shop and to have a plan that covers all
contingencies. Agile says why don't we just move next door to the
shop?
I'm currently investing a little of my time in contributing to the
department's process documents. I'm trying to get us to document much
more of the 'what we do'.
Let me explain why.
There are certain corners that should not be cut. We tend to cut them.
Often, we do this knowingly, because we can't see any better options.
We includes me.
Why, you ask?
Think of a race car. Now, driving through the ditch by the side of the
road is bad. But if you've come off the track, it's a risk you may
have to take.
The hard question is not "do we drive through the ditch again?". It
is,
or it should be, "how come we are off the track again?"
Often, we don't know. Part of the reason for that is much of we do
happens via undocumented pathways. People just find ways to make
things
work.
To return to the metaphor, we ran out of track, so we went
cross-country, and we thought we would pick up the track again, but now
it seems that it's on the other side of that ditch, so either we go
back
a million miles, or we go though the ditch. And we dropped the spare
fuel can the last time we went through a ditch so we don't actually
have
the fuel to backtrack. On the other hand, we don't exactly know where
that path goes either, so maybe we should just keep going cross
country.
Documentation is an aid to thinking, not a replacement for thinking.
Having a list of things that have to be done can be used to disempower
engineers. 'Go do this. Now do this.'
But, it can also be empowering. 'Sir, the process says that I need to
give this information to X. If I cut that corner, then X cannot ...'
If I have a map of the whole territory, I have some expectation of
arriving.
If the map turns out to be wrong, I have an understanding of what I can
do to get back on track, including the option of finding a new track.
Even if I chose the worst possible path, I can do better next time, if
I
record the path I took.
Once I've managed to follow the map a few times I won't need the map
any
more. I'll know a route that gets me where I want to go.
But if I struggle and guess and fumble through a different path each
time, and if I don't know which path I took, then I don't get feedback
on which of my many guesses were right or wrong and I'll probably never
learn.
When we aren't getting the outcomes we want, understanding the
difference between what actually do and what we think we should do is
valuable.
When things are left unsaid then we can believe different things and
have gaps in our knowledge and not realise that there is a problem.
When we have to say 'it is thus' such gaps become very obvious.
Regards, Ben A

Yahoo! Groups Links

<*> To visit your group on the web, go to:
http://groups.yahoo.com/group/xpbookdiscussiongroup/

<*> To unsubscribe from this group, send an email to:
xpbookdiscussiongroup-unsubscribe-***@public.gmane.org

<*> Your use of Yahoo! Groups is subject to:
http://docs.yahoo.com/info/terms/

[Brad Appleton]

Post by Steven Gordon
To stretch the analogy a bit further, would it ever make sense to file
all the shopping lists our wife has given us over the years? Would it
make sense to reference this old information the next time we have a
question instead of directly asking our wife?

Interesting question Steven! Thanks for posing it!

I agree with your conclusion when your question is phrased as above.
If I instead replace "instead of directly asking our wife" with "while
we are making up a new shopping list" then I think my answer is
altogether different.

Provided it is not much effort to "file" the shopping lists and to
search/sort thru the previous lists, I think it could indeed make sense
and prove useful to do so when making the next list. I think it could
help me by making me remember to ask certain questions or clarify
certain details, such as:

* Test-first checklist: what things are "usually" on my shopping list,
and do I need all the same things this time? or else did I omit one of
them this time, and if so was it an oversight or was I correct in
omitting it. (this gives me a "checklist" of the "usual suspects" so I
make a conscious decision about which one I do/dont need.

* Target audience: who is doing the shopping this week? and what
"typical" differences are there in the shopping lists made for me,
versus for my wife (e.g., do I need to include more detail/instructions
in this shopping list)

* Do I usually prefer a particular brand for a given item (e.g., of Milk
or juice) and did I specify a brand for that item that was different
from the "usual" one (to make sure I did it consciously rather than
unconsciously)

I guess my use of the "filed" checklist in this fashion would help me
compile a test-suite that I could regularly use to give me more feedback
about the completeness/correctness of the list in test-first fashion
while I create it (pairing with my wife of course :-)

Post by Steven Gordon
I think it would not make sense to file old shopping lists for future reference.

I notice this time you omitted the statement you had earlier which
clarified the intent/purpose of filing the old shopping lists. So the
statement now looks like a much more general one which rules out the
usefulness of compiling the shopping list as a database of
domain-specific requirements profile/composites that I can use to
examine trends in commonality and variability everytime I have to make a
new shopping list.

I think that application of filing the old lists is different from
filing them for the pur[ose of understanding the previous shopping list.
Each "shopping list" is quite possibly a new project in the same domain
(tho I suppose I could consider it a "new release" of a version of the
contents of my kitchen and cupboards :-)

Post by Steven Gordon
Analogously, I believe we should do however much
documentation and modeling is necessary to accomplish our current
objectives, but once those objective are attained and verified through
feedback, persisting most of that working documentation generally
creates more longterm overhead and misinformation than it is worth.

Ahh - here is the key ... "persisting most of that working
documentation" ... In my case, Im not necessarily persisting the old
shoppping list as some single living/evolving copy, Im indeed
"obsoleting" them (rather than persisting them) but am still interested
in the data for the purposes mentioned earlier above

Post by Steven Gordon
documentation that can be inferred from the tests and the code are
redundant, so we should dispose of that working documentation and move on.

I think its redundant, and should be disposed of if the code and tests
are "consumable" by all stakeholders that need that information.
Otherwise, instead of disposing of it entirely, I would try to see if I
could generate all other (redundant) forms from a single source of
information in a format that is easiest to maintain.

[Turpin, Jay]

Fair is fair. I probably stole it from you or someone else anyway :)

Regards,
Jay Turpin
Intel Corporation
"Character is doing what's right when nobody's looking." - J.C. Watts

-----Original Message-----
From: xpbookdiscussiongroup-***@public.gmane.org
[mailto:xpbookdiscussiongroup-***@public.gmane.org] On Behalf Of Ron Jeffries
Sent: Monday, April 25, 2005 1:26 AM
To: xpbookdiscussiongroup-***@public.gmane.org
Subject: Re: [xpe2e] Why do we spend time on documents?


Nice metaphor, Jay. Be assured that I'm going to steal it. With
attribution, most times.

Thanks,

Ron Jeffries
www.XProgramming.com
Will Turner: This is either madness or brilliance.
Captain Jack Sparrow: It's remarkable how often those two traits
coincide.

Post by Turpin, Jay
It really matters who is going to the store to do the shopping. If

it's

Post by Turpin, Jay
the wife (the expert shopper in most families), a shopping list with a
few items listed on it will do fine. She is able to intelligently make
substitutions if a particular item is unavailable and buy additional
things if an unplanned item is on sale.
However, if I am going to the store, I will need a list with much
greater detail. Which brand of spaghetti sauce should I get? What if
they are out of lima beans? Can black beans be substituted? My wife

can

Post by Turpin, Jay
only document some of the detail. She is unaware of the depth of my
ignorance in these matters. I will invariably make mistakes.
Agile development believes in shopping lists. But it also believes in
bringing our wives to the store with us. Or at least a cell phone, so

we

Post by Turpin, Jay
can call and clarify the requirements when we run off the road.

Yahoo! Groups Links