At 01:55 PM 9/28/2006 -0400, Bill Arnold wrote:
I think documentation is an imperative, for several reasons. But first
...
The greatest benefits of documentation are that it gives the programmer a road map of the entire system, something that cannot be gleaned from
...
In the last analysis, doc is a system, and like all systems, they work if they are regarded as important, and fail if they are neglected or considered unimportant. I've seen this in big companies with systems management activities, such as problem management. One company has it down to a science, another never got it.
...
Bill makes some good points, but Hal seems more directly attuned to the real world.
In my experience, in the real world, most software documentation is a mess. It could be primarily because management is lazy like Bill alludes to. Or it could be related to the fact that management usually shoves the documentation stuff off to 'writers' and 'developers' (managers don't understand software - I thought this would be better by now - it doesn't seem to be).
From what I've experienced, there should be a high-level document that describes the system. Put in user features, discuss conceptual flows, etc. Beyond that, the documentation becomes very cumbersome and therefore inaccurate (there are really only 2 kinds of documentation: out-of-date, and non-existent). Probably the only way to address this problem is to build the documentation into the source code itself. I think Python has some cool features/standards here, not sure about other languages. For most, it'd probably mean coming up with standards for code headers/comments, etc.
Of course, there are some things that really, absolutely need to be documented. External system interfaces for example. Database schema is another. These are things that should NOT be changing very often. If they do, it's likely to be an actual business situation vice fixing a bug, tweaking performance, etc.
I'm not sure what that "Agile" stuff is all about. You can't leave things completely uncontrolled/unknown for the whole project. If they really say no documentation at all, it sounds kind of flaky. I imagine the 'author' of that approach is probably just reeling from bad experiences where the other extreme is taken. For example, at one client site, there is a 'process' in place which requires laborious documentation throughout the development/maintenance process. From my statistics so far, it appears that about 70% to 80% of the time (total hours billed) spent on a software project solely revolves around this 'process' and the documentation it generates. From a developer's perspective, it's extremely frustrating to see a requested change, which takes all of 15 minutes to code/test, take 2-4 hours of effort in documenting stuff, and then take 2 weeks to finally be released. That type of environment breeds 'I-don't-care' developers. That is, hey I did my little piece, I passed it on. I don't care if it really works or how quickly it gets to the users. My management is grading me on how well I follow the processes. So, 'good' developers usually leave such an environment or find other outlets to spend their creative energy.
The thing is, no matter what development approach is taken, lots of doc, little doc, there is a key factor most places ignore. Development team motivation. You show me a motivated, empowered, and usually small development team, and I'll show you an unbeatable combination for a project. Such a team could be harmed by Agile or harmed by doc-to-the-max. And when the motivation is gone, so is the productivity. They key is to match the process to the team, not force the team to a process. Best situation: let the team choose the process they want. You may think the 'lazy' approach would always be taken. And maybe it would for the first project. But when a team actually sees they have the power to change things, you'd be surprised what results.
Of course, this will probably never happen in the big companies here in the US. Too much worry about CYA (so gotta dictate junk like "CMMI standard", etc). And it'll never happen at Government sites (where CYA is king, and most don't really care about the work being done).
-Charlie _______________________________________________ Post Messages to: [email protected] Subscription Maintenance: http://leafe.com/mailman/listinfo/profox OT-free version of this list: http://leafe.com/mailman/listinfo/profoxtech ** All postings, unless explicitly stated otherwise, are the opinions of the author, and do not constitute legal or medical advice. This statement is added to the messages for those lawyers who are too stupid to see the obvious.
