Darren New wrote:

> I know most programmers don't like to write documentation, but it's 
> always a little jarring to me to run across something like that.

My favourit one is where you got to www.mycoolapplication.org and it 
yells "Hey! It's free! It's open-source! And it rocks! It has features 
A, B, C, J, K, M, V, X, Y and Z!"

Yes, but WHAT DOES IT DO??!? >_<

Sometimes people are just too close to a project to remember that 
somebody else might not know this crucial information. Without that 
context, the rest often makes little or no sense.



For what it's worth, I know most programmers don't like writing 
documentation, but I see writing the manual as almost being like 
programming. A good computer program consists of a set of abstractions, 
and by writing a program you are "teaching" the computer to use your 
abstractions. Writing the documentation simply means teaching 
abstractions to a human instead. (Although the abstractions in question 
will usually not be the same - depending on what the program is supposed 
to be doing. Plus you don't have to explain how anything works, only how 
to use it.)

That said, I have found - with programming and documenting - that 
sometimes you just want to skip over the bit you're doing to get to the 
interesting part where all the cool stuff happens...

-- 
http://blog.orphi.me.uk/
http://www.zazzle.com/MathematicalOrchid*

Post a reply to this message