This post originated from an RSS feed registered with .NET Buzz
by Peter G Provost.
Original Post: Documentation, documentation, documentation
Feed Title: Peter Provost's Geek Noise
Feed URL: /error.aspx?aspxerrorpath=/Rss.aspx
Feed Description: Technology news, development articles, Microsoft .NET, and other stuff...
I asked for some documentation when I first got here. I looked at it, realized
that this was some “God-n-Country” documentation that basically was a cut-n-paste
of some Microsoft Marketing documentation for certain technologies, and
then asked for the programming documentation. There is no programming documenation
and the guys that originally developed this app have left.
My question to Wallace and everyone else out there is this:
Have you ever walked on to a legacy project and been given good documentation?
I haven't. I don't know anyone who has. I'm not saying "no documentation" is a good
thing, but I think people have a tendency to yell "WHERE ARE THE DOCS?" anytime they
have to take over someone else's code. The fact is, taking over someone else's code
sucks. No one writes code and cleanly as you do, and everyone makes decisions that
you wouldn't have made.
Right?
Even if you have been handed a bible of documentation, did you trust it? Did you just
end up reading the code anyway? I've certainly heard this before: "Yeah, that (points
to binder on desk) is the docs from the last release but they seem to be way out of
date, so I'm just reading the code."
I don't like this anymore than you do, but I happen to agree with the TDD guys who
preach that the code itself is the best documentation. If it is well written and clear,
you shouldn't need much more than a few pages of architectural and glossary information.
Maybe not even that.