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
-- 
http://www.piclist.com PIC/SX FAQ & list archive
View/change your membership options at
http://mailman.mit.edu/mailman/listinfo/piclist