You're both right. With a few notable exceptions, programmers shouldn't be the ones writing user manuals, and some shouldn't even be writing the system design docs. (Aliza and I are unusual, both being programmers who can write. Then again, maybe that's part of the reason we get Analyst or Programmer/Analyst status. Aliza is also an amazing tester, BTW.)
OTOH, programmers had bloody well better document what it is they're doing so that a) the Documentation People have some clues to work with, and b) the rest of the team, whoever has to maintain the code a couple years later, the programmer's manager, and the programer's two-years-later self can make sense of the code.
And that includes both inline comments and separate notations in changelogs, status reports, memos to the doc people, whatever.
I have actually turned in code that was 51% comments to 49% code. (Actually, that's not counting whitespace.) And I don't mean school stuff -- most of what I turned in as a student and (I think) all of what I've written as example code as a teacher has been more than 50% comments. (One example program was about 75% comments.) Most real-world code doesn't need to be that extreme, but it really ought to say what it's doing and why, at least in any place where the programmer had to stop and think about how to do it.
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)
OTOH, programmers had bloody well better document what it is they're doing so that a) the Documentation People have some clues to work with, and b) the rest of the team, whoever has to maintain the code a couple years later, the programmer's manager, and the programer's two-years-later self can make sense of the code.
And that includes both inline comments and separate notations in changelogs, status reports, memos to the doc people, whatever.
I have actually turned in code that was 51% comments to 49% code. (Actually, that's not counting whitespace.) And I don't mean school stuff -- most of what I turned in as a student and (I think) all of what I've written as example code as a teacher has been more than 50% comments. (One example program was about 75% comments.) Most real-world code doesn't need to be that extreme, but it really ought to say what it's doing and why, at least in any place where the programmer had to stop and think about how to do it.
(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...