PROGRAMMING : documentation and UML
I'm currently trying to make some useful documentation for work as I am leaving in 3 weeks (from today!!). As I sit here typing away, and drawing up diagrams, I am trying to find the balance between putting in so much detail that it immediately becomes out of date, or so little detail that it proves to be useless to the person reading it.
I am a strong believer that programming is all about communication. At the obvious level it is about communicating your intent to the computer, but it is also about communicating your intent to fellow programmers through your code (and comments therein), through your documentation and, most effectively, through your verbal 'knowledge transfer.'
Of those three forms of communication, documentation is the least useful - it is the quickest to go out of date, and the least accurate. Consequently, in my documentation I attempt to convey the most information in the smallest space possible. If i feel it's starting to get away from me then I try to take a step back and leave out some of the detail. In this way it might stay up to date for longer, it will hopefully supplement the code so people can more easily get on with the job of understanding the ifs and thens, and people might actually bother to look at it as they know it's only going to take a minute of their life, rather than waste an hour.
I would be interested to see how a team worked if they were required to created detailed and up to date documentation all the time. I would be interested to see how _I_ would deal with it - I think I might go insane!
The one time I did have to do this was at my first job. We had a large spec, some 160 pages long, that was to be used as the contract for the project we were doing. Consequently it _had_ to be accurate and detailed. It took us 18 months to produce just that document, and still wasn't finalized 6 months later after we'd started coding.
Actually, I suppose that this was one of the issues that the Rational stuff was supposed to deal with - keeping documentation up to date. I'm not sure that it really worked, but I guess the class diagrams etc could be kept up to date from the source, though I'm not sure that that would supply all that much more information than looking at the code...
I am a strong believer that programming is all about communication. At the obvious level it is about communicating your intent to the computer, but it is also about communicating your intent to fellow programmers through your code (and comments therein), through your documentation and, most effectively, through your verbal 'knowledge transfer.'
Of those three forms of communication, documentation is the least useful - it is the quickest to go out of date, and the least accurate. Consequently, in my documentation I attempt to convey the most information in the smallest space possible. If i feel it's starting to get away from me then I try to take a step back and leave out some of the detail. In this way it might stay up to date for longer, it will hopefully supplement the code so people can more easily get on with the job of understanding the ifs and thens, and people might actually bother to look at it as they know it's only going to take a minute of their life, rather than waste an hour.
I would be interested to see how a team worked if they were required to created detailed and up to date documentation all the time. I would be interested to see how _I_ would deal with it - I think I might go insane!
The one time I did have to do this was at my first job. We had a large spec, some 160 pages long, that was to be used as the contract for the project we were doing. Consequently it _had_ to be accurate and detailed. It took us 18 months to produce just that document, and still wasn't finalized 6 months later after we'd started coding.
Actually, I suppose that this was one of the issues that the Rational stuff was supposed to deal with - keeping documentation up to date. I'm not sure that it really worked, but I guess the class diagrams etc could be kept up to date from the source, though I'm not sure that that would supply all that much more information than looking at the code...
0 Comments:
Post a Comment
<< Home