标签: documentation

Recently, I had a modest troubleshooting assignment. I was involved in the mechanical repair of an interface box which had been removed from service, with four identical connectors hand-labeled as A, B, C and D, corresponding to internal channels. I was told that only channels A and B were live, and that C and D were disconnected internally. After I did the repair, I went on-site and reconnected the cables—which were conveniently labeled as a, b, c, and d—to their respective connectors. "All done," or so I thought. Well, not quite. The signals on cable "a" appeared at channel "B", while the signal of cable "b" didn't appear anywhere. It took a few minutes to realize the problem: those thoughtful labels A, B, C, and D on the box were wrong; I swapped things around, re-labeled the box's connectors correctly, and my work was done. But the incident got me thinking . This was a relatively simple case of mislabeling and incorrect documentation. But in many cases, the situation is far more complex, and the requisite documentation more vital. Yet often, we are given documentation which is incomplete or, perhaps worse, inaccurate. Then we spend our time trying to figure out which part of the documentation is correct and which is not, at the same time we are trying to debug the system itself. This documentation can be a system-level block diagram, a circuit schematic, or even a code listing. The other scenario is to have minimal or no documentation at all. In that case, you have fewer misconceptions about the correctness of what you've got, so you can't be misled. That's the good news. But you do need to unravel the design with a blank sheet of paper in front of you, so to speak, and that can be very tough. So here's the philosophical engineering question: is it better to have incorrect documentation which may help you get started, but which also may lead you astray; or to have no (or minimal) documentation which forces you to figure it out from scratch? What's been your experience? What's your preference?  

Language is important. That includes spelling and grammar, whether "your" writing ad copy or comments. (The word misuse is intentional). I served eight years of primary school education under the Catholic nuns, and four years of high school under the Jesuits. The nuns taught us to obey, and the Jesuits to think. Both drilled the importance of language and of writing into our unwilling skulls. So now I'm a bit of a language snob, and get irritated when seemingly intelligent people massacre English, the only language I know well. The one woodworking web site I follow, Sawmill Creek, is full of postings that confuse your and you're, its and it's, and there, their and they're. That seems to be common all over the Internet. Perhaps it's unreasonable to expect quick postings to meticulously follow every precept of grammar. One of the Web game-changers is how it connects people. Individuals spread over the entire globe can form instant friendships. No one would hold a casual telephone conversation to a high level of discourse, and it's just as unreasonable to expect the same from Internet board postings. (Conversely, the web is forever; today's rant feeds tomorrow's resume). But I certainly expect more from professional discourse. Ads, for instance, advertise both a product and the company's professionalism. So when I came across the following in Lufthansa's magazine, well, I couldn't decide whether to laugh or get angry:     The message I get from this: We're idiots. And we're happy to teach you to be idiots. The irony, of course, is that RosettaStone alleges to teach language. The double irony is that the sentence is perfectly constructed—had it been used in verbal dialog. In written form, the company appears incompetent. In the old days before word processors and spelling checkers, people learned to read copy carefully, even reading the entire ad backwards to prevent one's brain from slipping over obvious mistakes. None of us do that anymore, thankfully. But just as it's foolish to believe any answer that pops up in a spreadsheet or on a calculator, we really must use other tools, like the old noggin, to supplement spelling and grammar checkers. What does this have to do with embedded systems? Everything! Our comments and documentation must be proper English, assuming that's the language we're using. Comments are as important as the code. The code tells the computer what to do; the comments tell a future maintainer what your intent was. I reverse engineer a lot of code, and it's really hard to convert one person's "obvious" intentions encoded into C into something that makes sense. Write obtuse comments and you'll at best annoy the maintainer, and at worse baffle him. The real irony is that our tools don't even pretend to help us get the English right in our comments. The entire world expects Word to correct misspellings and underline poor grammar. But programmers are still stuck with illiterate '70s-era text editors.

Language is important. That includes spelling and grammar, whether "your" writing ad copy or comments. (The word misuse is intentional). I served eight years of primary school education under the Catholic nuns, and four years of high school under the Jesuits. The nuns taught us to obey, and the Jesuits to think. Both drilled the importance of language and of writing into our unwilling skulls. So now I'm a bit of a language snob, and get irritated when seemingly intelligent people massacre English, the only language I know well. The one woodworking web site I follow, Sawmill Creek, is full of postings that confuse your and you're, its and it's, and there, their and they're. That seems to be common all over the Internet. Perhaps it's unreasonable to expect quick postings to meticulously follow every precept of grammar. One of the Web game-changers is how it connects people. Individuals spread over the entire globe can form instant friendships. No one would hold a casual telephone conversation to a high level of discourse, and it's just as unreasonable to expect the same from Internet board postings. (Conversely, the web is forever; today's rant feeds tomorrow's resume). But I certainly expect more from professional discourse. Ads, for instance, advertise both a product and the company's professionalism. So when I came across the following in Lufthansa's magazine, well, I couldn't decide whether to laugh or get angry:     The message I get from this: We're idiots. And we're happy to teach you to be idiots. The irony, of course, is that RosettaStone alleges to teach language. The double irony is that the sentence is perfectly constructed—had it been used in verbal dialog. In written form, the company appears incompetent. In the old days before word processors and spelling checkers, people learned to read copy carefully, even reading the entire ad backwards to prevent one's brain from slipping over obvious mistakes. None of us do that anymore, thankfully. But just as it's foolish to believe any answer that pops up in a spreadsheet or on a calculator, we really must use other tools, like the old noggin, to supplement spelling and grammar checkers. What does this have to do with embedded systems? Everything! Our comments and documentation must be proper English, assuming that's the language we're using. Comments are as important as the code. The code tells the computer what to do; the comments tell a future maintainer what your intent was. I reverse engineer a lot of code, and it's really hard to convert one person's "obvious" intentions encoded into C into something that makes sense. Write obtuse comments and you'll at best annoy the maintainer, and at worse baffle him. The real irony is that our tools don't even pretend to help us get the English right in our comments. The entire world expects Word to correct misspellings and underline poor grammar. But programmers are still stuck with illiterate '70s-era text editors.