Argh, there are so many things being said in this thread that I just have to respond to...
My general rule of thumb is "if I have to look it up, I have to document it." If that means breaking a system call into seven lines of code so that I can put an explanation beside each parameter, so be it. This is also self-preservation, in a case where I'm going to be maintaining and improving the same software over a long period of time.
Documentation requirements can go to far, though, as when a programmer declared integers I, J, and K, and in the required comment labelled them as "Ye Olde Loop Variables".
In some cases, asking programmers to write user documentation is just not going to work. Or, at best, will result in a document written in "Engineer", which then has to be translated into "User-Friendly English".
For some reason I'm thinking back to Tom Kelsall and his overly verbose problem reports. Tom couldn't sneeze in less than a full paragraph. Tom was a scientist. A trained observer. So he would faithfully write an essay about what he had observed the software doing, much like a Martian observing human culture would do. He didn't try to understand what was going wrong, or why. He simply documented what he saw, and handed his observations over to the programmers who would Make Things Better. When handed a set of his problem reports, it was immediately obvious what had happened. When I figured out what was actually wrong with the software, I would write another problem report, describing what was wrong with the software, with a terse reference to the incorrect output observed. Then, the change order could reference both the scientist's view and the programmer's view. Tom, if you ever read this, I really enjoyed working with you...
(no subject)
My general rule of thumb is "if I have to look it up, I have to document it." If that means breaking a system call into seven lines of code so that I can put an explanation beside each parameter, so be it. This is also self-preservation, in a case where I'm going to be maintaining and improving the same software over a long period of time.
Documentation requirements can go to far, though, as when a programmer declared integers I, J, and K, and in the required comment labelled them as "Ye Olde Loop Variables".
In some cases, asking programmers to write user documentation is just not going to work. Or, at best, will result in a document written in "Engineer", which then has to be translated into "User-Friendly English".
For some reason I'm thinking back to Tom Kelsall and his overly verbose problem reports. Tom couldn't sneeze in less than a full paragraph. Tom was a scientist. A trained observer. So he would faithfully write an essay about what he had observed the software doing, much like a Martian observing human culture would do. He didn't try to understand what was going wrong, or why. He simply documented what he saw, and handed his observations over to the programmers who would Make Things Better. When handed a set of his problem reports, it was immediately obvious what had happened. When I figured out what was actually wrong with the software, I would write another problem report, describing what was wrong with the software, with a terse reference to the incorrect output observed. Then, the change order could reference both the scientist's view and the programmer's view. Tom, if you ever read this, I really enjoyed working with you...