|
![](/i/fill.gif) |
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
|
![](/i/fill.gif) |