Monday, April 16, 2007

Is documentation really that useful?

I know a lot of managers feel that a system should have a certain amount of documentation supporting it, but in my experience often
documentation that is produced for this purpose never gets used after it is written. I would suspect some sort of high level design of the system which describes it's interfaces, major architectural components and design patterns is useful. Perhaps also a support/operations manual for those that need to support the system in production can be useful. However when it gets down to detailed design documents such as class diagrams and sequence diagrams I rarely find them useful. Usually they don't get maintained and they just don't help you understand the system that much.

Although I'm not totally convinced I'm starting to lean towards the idea that good software is self documenting and software quality is more important than documentation. Also having been involved in some agile projects lately, I'm starting to see how the automated tests for a system can be the best documentation of what the system does.

Saturday, April 14, 2007

Java is too complicated

I'm trying to get hibernate and spring working together and finding it REALLY REALLY frustrating to get simple transactions working. Google hasn't come to my rescue yet. In this case I suspect it is because there are some many variations of how you configure it and not many people are using it the way I'm trying to (maybe that is the problem...) I'm thinking this is probably a common experience. These frameworks are extremely powerful but also awfully complicated and hard to master.