"Building a system that conforms to the spec is easy.
Writing a spec that clearly describes what you want is
impossible." (from a
button mentioned by jducoer)
Unfortunately, the last spec I wrote was for a system whose parameters had been set politically, rather than technically.
Shades of PMS*...
* PMS = Project Management System, a nightmare of a software development fiasco that Glenn and I worked on lo, those many years ago. But the 12-volume spec I ended up writing was *good*.
Funny, I was just describing that project to someone a week ago. "You didn't tell me the project was in dBase!" "That's okay, you know dBase, don't you?" "Not yet..." And when it was revealed that our coder who impressed them so much wasn't old enough to buy beer.
(For folks coming in late, not only were some of the parameters of PMS set for goofy political reasons -- I wound up designing a subsystem to implement a distributed database using dBase III with record locking over sneakernet because of the goofy political stuff -- but the contract had been written in such a way that the client could keep changing requirements without changing deadlines. And the client was ... uh, let's call it "confused" ... enough that every time we gave him what he wanted, he couldn't remember the previous meeting and told us no, he meant something different. We were subcontractors brought in as firefighters. We worked magic, at significant metabolic cost, but we were younger then. Not as young as that coder, but still...)
Hey, if it was tough to code, it should be tough to understand!
(No, I don't believe that. In fact, I once rejected my own boss's software delivery because it had *no* comments documenting the change he was making...)
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...
Tech writer is a grossly underappreciated position. I can do that job (on top of the programming and design) -- and even do it well -- but oh how much more pleasant it is to hand it to someone who does it more quickly and actually doesn't mind doing it! Hey, free up more of my time for the design and coding. I'll write the design documents, someone else can bang those into the corporate format and write the user manuals and marketing copy.
Then there are the teams where nobody does the tech writing well except the actual tech writer, and the first time they get into a budget crunch they let the tech writer go "because they're not important to making the deadline", and it's invariably a Big Mistake.
Hmm. Everybody pays attention to the quarterback, but if the center doesn't do a good job, the quarterback is in a world of hurt.
![[personal profile]](https://www.dreamwidth.org/img/silk/identity/user.png){kind=small}
![[livejournal.com profile]](https://www.dreamwidth.org/img/external/lj-userinfo.gif){kind=small}
(no subject)
Shades of PMS*...
* PMS = Project Management System, a nightmare of a software development fiasco that Glenn and I worked on lo, those many years ago. But the 12-volume spec I ended up writing was *good*.
(no subject)
(For folks coming in late, not only were some of the parameters of PMS set for goofy political reasons -- I wound up designing a subsystem to implement a distributed database using dBase III with record locking over sneakernet because of the goofy political stuff -- but the contract had been written in such a way that the client could keep changing requirements without changing deadlines. And the client was ... uh, let's call it "confused" ... enough that every time we gave him what he wanted, he couldn't remember the previous meeting and told us no, he meant something different. We were subcontractors brought in as firefighters. We worked magic, at significant metabolic cost, but we were younger then. Not as young as that coder, but still...)
And yes, you kicked ass on that spec.
(no subject)
(no subject)
(no subject)
(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...
(no subject)
Then there are the teams where nobody does the tech writing well except the actual tech writer, and the first time they get into a budget crunch they let the tech writer go "because they're not important to making the deadline", and it's invariably a Big Mistake.
Hmm. Everybody pays attention to the quarterback, but if the center doesn't do a good job, the quarterback is in a world of hurt.