[AM] Plato on Documentation

[Scott Ambler]

Plato once said “…anyone who leaves behind him a written manual, and
likewise anyone who receives it, in the belief that such writing will be
clear and certain, must be exceedingly simple-minded…”. Thoughts?

- Scott

====================================================
Scott W. Ambler
Senior Consultant, Ronin International, Inc.
www.ronin-intl.com/company/scottAmbler.html

www.agiledata.org
www.agilemodeling.com
www.ambysoft.com
www.enterpriseunifiedprocess.info
www.modelingstyle.info
www.ronin-intl.com

For more information about AM, visit the Agile Modeling Home Page at www.agilemodeling.com
--^----------------------------------------------------------------
This email was sent to: gcma-***@gmane.org

EASY UNSUBSCRIBE click here: http://topica.com/u/?bUrKDA.bWnbtk.Z2NtYS1h
Or send an email to: agilemodeling-***@topica.com

For Topica's complete suite of email marketing solutions visit:
http://www.topica.com/?p=TEXFOOTER
--^----------------------------------------------------------------

[Tiseo, Paul]

From: Scott Ambler [mailto:***@ronin-intl.com]
Sent: Friday, March 12, 2004 11:36 AM

Plato once said "...anyone who leaves behind him a written manual, and
likewise anyone who receives it, in the belief that such writing will be
clear and certain, must be exceedingly simple-minded...". Thoughts?

Yeah. He didn't have to support his writings in an enterprise production
environment with standards compliance, legal ramifications, employee
turnover, etc! :)

Joking aside, does being skeptical of the usefulness of a document before
reading it preclude the fact that a clear and certain one can be written?

The emphasis that any given agile methodology puts on "people over process"
(and that certain agilists take to a cowboy extreme) is in fact a two-edged
sword. While I generally approve of that concept in its idealized form, the
fact is that the world is full of incompetent processes *AND* people. The
idea that all of one is any better than all of another is what is
"exceedingly simple-minded".

Sometimes we get so into debating A vs. B, that we overlook A+B or A*B.

_________________________________
Paul Tiseo, Systems Programmer
Research Computing Facility
Mayo Clinic Jacksonville, Griffin 371
***@mayo.edu
 

-----Original Message-----
- Scott
====================================================
Scott W. Ambler
Senior Consultant, Ronin International, Inc.
www.ronin-intl.com/company/scottAmbler.html
www.agiledata.org
www.agilemodeling.com
www.ambysoft.com
www.enterpriseunifiedprocess.info
www.modelingstyle.info
www.ronin-intl.com
For more information about AM, visit the Agile Modeling Home Page at
www.agilemodeling.com

For more information about AM, visit the Agile Modeling Home Page at www.agilemodeling.com
--^----------------------------------------------------------------
This email was sent to: gcma-***@gmane.org

EASY UNSUBSCRIBE click here: http://topica.com/u/?bUrKDA.bWnbtk.Z2NtYS1h
Or send an email to: agilemodeling-***@topica.com

For Topica's complete suite of email marketing solutions visit:
http://www.topica.com/?p=TEXFOOTER
--^----------------------------------------------------------------

[U***@aol.com]

This is why I'm an Aristotelian.

Kendall Scott

For more information about AM, visit the Agile Modeling Home Page at www.agilemodeling.com
--^----------------------------------------------------------------
This email was sent to: gcma-***@gmane.org

EASY UNSUBSCRIBE click here: http://topica.com/u/?bUrKDA.bWnbtk.Z2NtYS1h
Or send an email to: agilemodeling-***@topica.com

For Topica's complete suite of email marketing solutions visit:
http://www.topica.com/?p=TEXFOOTER
--^----------------------------------------------------------------

[Jason Gorman]

I like to think of documentation as a sort of luxury wallpaper...


_____

From: ***@aol.com [mailto:***@aol.com]
Sent: 12 March 2004 17:23
To: ***@topica.com
Subject: Re: [AM] Plato on Documentation


This is why I'm an Aristotelian.

Kendall Scott

For more information about AM, visit the Agile Modeling Home Page at
www.agilemodeling.com

For more information about AM, visit the Agile Modeling Home Page at www.agilemodeling.com
--^----------------------------------------------------------------
This email was sent to: gcma-***@gmane.org

EASY UNSUBSCRIBE click here: http://topica.com/u/?bUrKDA.bWnbtk.Z2NtYS1h
Or send an email to: agilemodeling-***@topica.com

For Topica's complete suite of email marketing solutions visit:
http://www.topica.com/?p=TEXFOOTER
--^----------------------------------------------------------------

[Paul Oldfield]

(responding to Scott)

Plato once said "...anyone who leaves behind him a written manual, and
likewise anyone who receives it, in the belief that such writing will be
clear and certain, must be exceedingly simple-minded...". Thoughts?

There are many times when I have read what some learned person
has written on a topic, and thought I understood the ideas he was
trying to convey, only to realise, sometimes much later, that I
undersood very little on this first introduction to a topic.

Having tried to read one of the more modern philosophers, I am
for once sure I didn't understand what he was trying to say.
Recently I have read some things (no names, no pack drill)
where I've been quite convinced *they* didn't understand what they
were trying to say.

I believe the mind needs to be in a certain state to be receptive
to the ideas that the author attempts to convey. This is all the
more reason for the author to consider carefully his intended
audience, and the ways in which they may be expected to think.


Paul Oldfield

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
www.aptprocess.com

any opinions expressed herein are not necessarily those of
Mentors of Cally or the Appropriate Process Movement
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

For more information about AM, visit the Agile Modeling Home Page at www.agilemodeling.com
--^----------------------------------------------------------------
This email was sent to: gcma-***@gmane.org

EASY UNSUBSCRIBE click here: http://topica.com/u/?bUrKDA.bWnbtk.Z2NtYS1h
Or send an email to: agilemodeling-***@topica.com

For Topica's complete suite of email marketing solutions visit:
http://www.topica.com/?p=TEXFOOTER
--^----------------------------------------------------------------

[p***@aol.com]

In a message dated 3/12/2004 12:00:46 PM Pacific Standard Time,
***@compuserve.com writes:
I believe the mind needs to be in a certain state to be receptive
to the ideas that the author attempts to convey. This is all the
more reason for the author to consider carefully his intended
audience, and the ways in which they may be expected to think.
Paul:

Very perceptive. I suspect the same appreciation for the audience should
apply to conversations, as well.

Regards,

Pete

For more information about AM, visit the Agile Modeling Home Page at www.agilemodeling.com
--^----------------------------------------------------------------
This email was sent to: gcma-***@gmane.org

EASY UNSUBSCRIBE click here: http://topica.com/u/?bUrKDA.bWnbtk.Z2NtYS1h
Or send an email to: agilemodeling-***@topica.com

For Topica's complete suite of email marketing solutions visit:
http://www.topica.com/?p=TEXFOOTER
--^----------------------------------------------------------------

[p***@aol.com]

In a message dated 3/12/2004 8:49:29 AM Pacific Standard Time,
***@mayo.edu writes:
The emphasis that any given agile methodology puts on "people over process"
(and that certain agilists take to a cowboy extreme) is in fact a two-edged
sword. While I generally approve of that concept in its idealized form, the
fact is that the world is full of incompetent processes *AND* people. The
idea that all of one is any better than all of another is what is
"exceedingly simple-minded".

Sometimes we get so into debating A vs. B, that we overlook A+B or A*B.
Paul:

Words well writ.

Regards,

Pete

For more information about AM, visit the Agile Modeling Home Page at www.agilemodeling.com
--^----------------------------------------------------------------
This email was sent to: gcma-***@gmane.org

EASY UNSUBSCRIBE click here: http://topica.com/u/?bUrKDA.bWnbtk.Z2NtYS1h
Or send an email to: agilemodeling-***@topica.com

For Topica's complete suite of email marketing solutions visit:
http://www.topica.com/?p=TEXFOOTER
--^----------------------------------------------------------------

[Paul Oldfield]

(responding to Pete)

Post by p***@aol.com

Post by Paul Oldfield
I believe the mind needs to be in a certain state to be receptive
to the ideas that the author attempts to convey. This is all the
more reason for the author to consider carefully his intended
audience, and the ways in which they may be expected to think.

Very perceptive. I suspect the same appreciation for the audience
should apply to conversations, as well.

I don't know about other folk, but I find that ideas I can describe
lucidly and to the point in writing come out of my mouth in a
jumbled, unintelligible mush. One-to-one it isn't too bad, I can
look at the ceiling and stroke my beard a few times while I
gather my thoughts... and throw in a placeholder; "Hmm...
it depends..." ;-)

Paul Oldfield

For more information about AM, visit the Agile Modeling Home Page at www.agilemodeling.com
--^----------------------------------------------------------------
This email was sent to: gcma-***@gmane.org

EASY UNSUBSCRIBE click here: http://topica.com/u/?bUrKDA.bWnbtk.Z2NtYS1h
Or send an email to: agilemodeling-***@topica.com

For Topica's complete suite of email marketing solutions visit:
http://www.topica.com/?p=TEXFOOTER
--^----------------------------------------------------------------

[p***@aol.com]

In a message dated 3/13/2004 2:24:37 AM Pacific Standard Time,
***@compuserve.com writes:
I don't know about other folk, but I find that ideas I can describe
lucidly and to the point in writing come out of my mouth in a
jumbled, unintelligible mush. One-to-one it isn't too bad, I can
look at the ceiling and stroke my beard a few times while I
gather my thoughts... and throw in a placeholder; "Hmm...
it depends..." ;-)
Boy, do I hear you...I'm often in the same fix, and unfortunately, I'm
usually the one chosen who to do the talking, presenting, explaining, etc. A friend
of my father used to tell me that the best prop in these stuations is a pipe:
when you get stuck, you can always pull it out, load it up, and puff away
while gathering your thoughts. When I asked him why I'd never seen him smoking a
pipe, he told me he'd had to choose between a pipe and a beard, because in his
case, they were mutually exclusive for sake of his safety. As a young man, he
was called upon to make a presentation at a shareholder's meeting. In a
question and answer period at th end of the slide show, he took a moment to "gather
his thoughts", and set his beard on fire. And that was that.

Regards,

Pete

For more information about AM, visit the Agile Modeling Home Page at www.agilemodeling.com
--^----------------------------------------------------------------
This email was sent to: gcma-***@gmane.org

EASY UNSUBSCRIBE click here: http://topica.com/u/?bUrKDA.bWnbtk.Z2NtYS1h
Or send an email to: agilemodeling-***@topica.com

For Topica's complete suite of email marketing solutions visit:
http://www.topica.com/?p=TEXFOOTER
--^----------------------------------------------------------------

[David Robrecht]

I agree. I never expect my documents to be clear. But I do write them and sometimes expect documentation from others.

To often a manual is "used" to escape explaining the content of it interactively.
People think it will save them time when they write down what they know and then expect the document to be self explaining.
The result of this is that a lot of people do not understand the document and cannot get a good introduction or explanation because they "should" read and understand the manual.

This observation too often leads to disappointment and the conclusion that documention serves no purpose.
The result of this beeing a lot of time spent on a multitude of private documentation to preserve the memory of the explanation received.

Documentation to me is what I give to others so that they do not need to take notes when I am talking to them. Documentation is also something to write your own notes on. It does not exclude the need for real interaction about the subject.

Robrecht


-----Oorspronkelijk bericht-----
Van: Scott Ambler [mailto:***@ronin-intl.com]
Verzonden: vr 12/03/2004 17:35
Aan: ***@topica.com
CC:
Onderwerp: [AM] Plato on Documentation



Plato once said “
anyone who leaves behind him a written manual, and
likewise anyone who receives it, in the belief that such writing will be
clear and certain, must be exceedingly simple-minded
”. Thoughts?

- Scott

====================================================
Scott W. Ambler
Senior Consultant, Ronin International, Inc.
www.ronin-intl.com/company/scottAmbler.html

www.agiledata.org
www.agilemodeling.com
www.ambysoft.com
www.enterpriseunifiedprocess.info
www.modelingstyle.info
www.ronin-intl.com

For more information about AM, visit the Agile Modeling Home Page at www.agilemodeling.com






For more information about AM, visit the Agile Modeling Home Page at www.agilemodeling.com
--^----------------------------------------------------------------
This email was sent to: gcma-***@gmane.org

EASY UNSUBSCRIBE click here: http://topica.com/u/?bUrKDA.bWnbtk.Z2NtYS1h
Or send an email to: agilemodeling-***@topica.com

For Topica's complete suite of email marketing solutions visit:
http://www.topica.com/?p=TEXFOOTER
--^----------------------------------------------------------------

[t***@bdk.rug.nl]

(responding to Scott)

Plato once said "...anyone who leaves behind him a written manual, and
likewise anyone who receives it, in the belief that such writing will be
clear and certain, must be exceedingly simple-minded...". Thoughts?

Based on the rule (?) that a judgment tells more about the judge than
about what is judged, may we conclude that Plato was a lousy writer?

To me it only seems handy to document what you're doing. However
ununderstandable it may be, a written story is easier to remember (or
to reread) than oral history. BTW, if you cannot write clearly, can you
explain clearly in speech?

Regards,

Thomas de Boer
University of Groningen
The Netherlands

For more information about AM, visit the Agile Modeling Home Page at www.agilemodeling.com
--^----------------------------------------------------------------
This email was sent to: gcma-***@gmane.org

EASY UNSUBSCRIBE click here: http://topica.com/u/?bUrKDA.bWnbtk.Z2NtYS1h
Or send an email to: agilemodeling-***@topica.com

For Topica's complete suite of email marketing solutions visit:
http://www.topica.com/?p=TEXFOOTER
--^----------------------------------------------------------------

[David Putman]

Post by Paul Oldfield
(responding to Scott)
Plato once said "...anyone who leaves behind him a written manual, and
likewise anyone who receives it, in the belief that such writing will be
clear and certain, must be exceedingly simple-minded...". Thoughts?

Eats, shoots and Leaves ?
Buffalo buffalo buffalo Buffalo buffalo ?
What! Is this thing called love?

Dave Putman

For more information about AM, visit the Agile Modeling Home Page at www.agilemodeling.com
--^----------------------------------------------------------------
This email was sent to: gcma-***@gmane.org

EASY UNSUBSCRIBE click here: http://topica.com/u/?bUrKDA.bWnbtk.Z2NtYS1h
Or send an email to: agilemodeling-***@topica.com

For Topica's complete suite of email marketing solutions visit:
http://www.topica.com/?p=TEXFOOTER
--^----------------------------------------------------------------

[Joel Karafin]

Well said!
-JCK

-----Original Message-----
From: David Robrecht [mailto:***@realsoftware.be]
Sent: Monday, March 15, 2004 3:12 AM
To: ***@topica.com
Subject: RE: [AM] Plato on Documentation


I agree. I never expect my documents to be clear. But I do write them and
sometimes expect documentation from others.

To often a manual is "used" to escape explaining the content of it
interactively.
People think it will save them time when they write down what they know and
then expect the document to be self explaining.
The result of this is that a lot of people do not understand the document
and cannot get a good introduction or explanation because they "should" read
and understand the manual.

This observation too often leads to disappointment and the conclusion that
documention serves no purpose.
The result of this beeing a lot of time spent on a multitude of private
documentation to preserve the memory of the explanation received.

Documentation to me is what I give to others so that they do not need to
take notes when I am talking to them. Documentation is also something to
write your own notes on. It does not exclude the need for real interaction
about the subject.

Robrecht


-----Oorspronkelijk bericht-----
Van: Scott Ambler [mailto:***@ronin-intl.com]
Verzonden: vr 12/03/2004 17:35
Aan: ***@topica.com
CC:
Onderwerp: [AM] Plato on Documentation



Plato once said "...anyone who leaves behind him a written manual, and
likewise anyone who receives it, in the belief that such writing will be
clear and certain, must be exceedingly simple-minded...". Thoughts?

- Scott

====================================================
Scott W. Ambler
Senior Consultant, Ronin International, Inc.
www.ronin-intl.com/company/scottAmbler.html

www.agiledata.org
www.agilemodeling.com
www.ambysoft.com
www.enterpriseunifiedprocess.info
www.modelingstyle.info
www.ronin-intl.com

For more information about AM, visit the Agile Modeling Home Page at
www.agilemodeling.com

For more information about AM, visit the Agile Modeling Home Page at www.agilemodeling.com
--^----------------------------------------------------------------
This email was sent to: gcma-***@gmane.org

EASY UNSUBSCRIBE click here: http://topica.com/u/?bUrKDA.bWnbtk.Z2NtYS1h
Or send an email to: agilemodeling-***@topica.com

For Topica's complete suite of email marketing solutions visit:
http://www.topica.com/?p=TEXFOOTER
--^----------------------------------------------------------------