Documentation boggle of the day
-
Ah, the joys of reading text by people who've heard that you shouldn't use the same word too often. Look on the bright side: at least you've got something to complain about.
I wanna be a eunuchs developer! Pass me a bread knife!
Mark_Wallace wrote:
at least you've got something to complain about
To quote a line: don't get me started ;P.
Software Zen:
delete this; -
Your sig is somehow very fitting to this thread.
Wrong is evil and must be defeated. - Jeff Ello
The Typo "to" instead of "too", or the essence of the message? :)
-
From the TCP/IP interface specification for some hardware I have to talk to: A command is always sent from the CT to the WS and a response is always sent from the WS to the CT. The term command and response no longer dictate the order that the messages are sent, that is, the WS may send a response first and the CT will respond by sending a command. And people wonder why I don't have any hair left...
Software Zen:
delete this;We had a "problem" with the elevator in the new wing of our office building: It goes from floor 4 to 3 to 2 to 1 to -1. Most of my colleagues have an engineering/math background, and it hurt our brains to see a discontinous number line to describe a physically continous world. So we ended up with declaring that the elevator shaft does have a virtual floor zero, where the elevator won't stop (because the floor is virtual). That eased our minds: The number line is again continous. You could try a similar approach for peace of mind: You may assume that there was a request, but it was virtual, so no real bits crossed the interface. The command provokes a virtual response, with no real bits transmitted. That way you can maintain a command/response model without breaking any sort of logic thinking.
-
From the TCP/IP interface specification for some hardware I have to talk to: A command is always sent from the CT to the WS and a response is always sent from the WS to the CT. The term command and response no longer dictate the order that the messages are sent, that is, the WS may send a response first and the CT will respond by sending a command. And people wonder why I don't have any hair left...
Software Zen:
delete this; -
Apparently a rhetorical answer is just as powerful as a rhetorical ques... Wait, that won't work, either. :confused:
-Bob
You're actually close to my solution. When I'm reading the spec, I mentally substitute the word 'message' for both 'command' and 'response'. It makes the whole thing much more readable, because you don't have that constant hitch figuring out which direction the traffic is going.
Software Zen:
delete this; -
From the TCP/IP interface specification for some hardware I have to talk to: A command is always sent from the CT to the WS and a response is always sent from the WS to the CT. The term command and response no longer dictate the order that the messages are sent, that is, the WS may send a response first and the CT will respond by sending a command. And people wonder why I don't have any hair left...
Software Zen:
delete this;Made sense to me. Though if you could say what "CT" means. Computed Tomography, Central Time, Console Terminal, Connecticut, ????
-
From the TCP/IP interface specification for some hardware I have to talk to: A command is always sent from the CT to the WS and a response is always sent from the WS to the CT. The term command and response no longer dictate the order that the messages are sent, that is, the WS may send a response first and the CT will respond by sending a command. And people wonder why I don't have any hair left...
Software Zen:
delete this;I really hate it when people attempt to redefine words.
Gary Wheeler wrote:
The term command and response no longer dictate the order that the messages are sent, that is,
Yes, they do! It is not a response if it comes first. It seems they are also attempting to redefine the word "always." In other words, it always happens except when it doesn't. That is truly ridiculous. I once got a new version of a device from a customer and I called them up and asked if it is the same as the old version. He said, yes, it is the same but enhanced. The fact is it was nothing like the previous version. That was rather annoying as I had to rewrite my driver for it.
"They have a consciousness, they have a life, they have a soul! Damn you! Let the rabbits wear glasses! Save our brothers! Can I get an amen?"
-
From the TCP/IP interface specification for some hardware I have to talk to: A command is always sent from the CT to the WS and a response is always sent from the WS to the CT. The term command and response no longer dictate the order that the messages are sent, that is, the WS may send a response first and the CT will respond by sending a command. And people wonder why I don't have any hair left...
Software Zen:
delete this; -
"the WS may send a response first and the CT will respond by sending a command." Sounds like Jeopardy! to me...
I'll take 'elephanting specifications' for $400 Alex.
"the debugger doesn't tell me anything because this code compiles just fine" - random QA comment "Facebook is where you tell lies to your friends. Twitter is where you tell the truth to strangers." - chriselst "I don't drink any more... then again, I don't drink any less." - Mike Mullikins uncle
-
From the TCP/IP interface specification for some hardware I have to talk to: A command is always sent from the CT to the WS and a response is always sent from the WS to the CT. The term command and response no longer dictate the order that the messages are sent, that is, the WS may send a response first and the CT will respond by sending a command. And people wonder why I don't have any hair left...
Software Zen:
delete this;When you reach the world of Enlightenment according to Zen, there's neither time nor causality anymore. Without time, you cannot say which item came first: response or command. And now, consequently, it is not possible to tell if a response was caused by a command, or a command was caused by a response. Om. :)
Oh sanctissimi Wilhelmus, Theodorus, et Fredericus!
-
I'll take 'elephanting specifications' for $400 Alex.
"the debugger doesn't tell me anything because this code compiles just fine" - random QA comment "Facebook is where you tell lies to your friends. Twitter is where you tell the truth to strangers." - chriselst "I don't drink any more... then again, I don't drink any less." - Mike Mullikins uncle
:laugh:
Software Zen:
delete this; -
I really hate it when people attempt to redefine words.
Gary Wheeler wrote:
The term command and response no longer dictate the order that the messages are sent, that is,
Yes, they do! It is not a response if it comes first. It seems they are also attempting to redefine the word "always." In other words, it always happens except when it doesn't. That is truly ridiculous. I once got a new version of a device from a customer and I called them up and asked if it is the same as the old version. He said, yes, it is the same but enhanced. The fact is it was nothing like the previous version. That was rather annoying as I had to rewrite my driver for it.
"They have a consciousness, they have a life, they have a soul! Damn you! Let the rabbits wear glasses! Save our brothers! Can I get an amen?"
Rick York wrote:
I really hate it when people attempt to redefine words.
Indeed. This is one of the hazards of working with all too many engineers. One of the critical "soft skills" is the ability to express yourself using appropriate vocabulary. It's also one of the skills that are looked on with contempt by too many engineers. I think I understand now why I'm the UI guy :rolleyes: in my group...
Software Zen:
delete this; -
When you reach the world of Enlightenment according to Zen, there's neither time nor causality anymore. Without time, you cannot say which item came first: response or command. And now, consequently, it is not possible to tell if a response was caused by a command, or a command was caused by a response. Om. :)
Oh sanctissimi Wilhelmus, Theodorus, et Fredericus!
I really need to hire you in as a consultant to work with this guy. Unfortunately we haven't had consultant money in years, so... :|
Software Zen:
delete this; -
From the TCP/IP interface specification for some hardware I have to talk to: A command is always sent from the CT to the WS and a response is always sent from the WS to the CT. The term command and response no longer dictate the order that the messages are sent, that is, the WS may send a response first and the CT will respond by sending a command. And people wonder why I don't have any hair left...
Software Zen:
delete this; -
From the TCP/IP interface specification for some hardware I have to talk to: A command is always sent from the CT to the WS and a response is always sent from the WS to the CT. The term command and response no longer dictate the order that the messages are sent, that is, the WS may send a response first and the CT will respond by sending a command. And people wonder why I don't have any hair left...
Software Zen:
delete this; -
I really need to hire you in as a consultant to work with this guy. Unfortunately we haven't had consultant money in years, so... :|
Software Zen:
delete this;You should try saying the money hum: Om money padme hum :)
Freedom is the freedom to say that two plus two make four. If that is granted, all else follows. -- 6079 Smith W.
-
From the TCP/IP interface specification for some hardware I have to talk to: A command is always sent from the CT to the WS and a response is always sent from the WS to the CT. The term command and response no longer dictate the order that the messages are sent, that is, the WS may send a response first and the CT will respond by sending a command. And people wonder why I don't have any hair left...
Software Zen:
delete this;Methinks they might have been physicists writing the documentation. They must've been struggling with the relativity / causality issues and trying to come to grips with the implications. I.e. in their mind effect may in fact precede cause. Thus the command may follow the result, which may all have happened weeks before the request!
-
From the TCP/IP interface specification for some hardware I have to talk to: A command is always sent from the CT to the WS and a response is always sent from the WS to the CT. The term command and response no longer dictate the order that the messages are sent, that is, the WS may send a response first and the CT will respond by sending a command. And people wonder why I don't have any hair left...
Software Zen:
delete this;Gary Wheeler wrote:
A command is always sent from the CT to the WS and a response is always sent from the WS to the CT. The term command and response no longer dictate the order that the messages are sent, that is, the WS may send a response first and the CT will respond by sending a command.
I think it's just the software engineer being stuck on the English language rather than focusing on the logical aspect of the documentation. Gratuitous network responses are very common in the networking world. [Gratuitous ARP Response](https://wiki.wireshark.org/Gratuitous\_ARP) There are also gratuitous RIP and eBGP responses. Probably a dozen other network protocols supporting gratuitous response messages. That's all I can think of at the moment. Best Wishes, -David Delaune
-
Gary Wheeler wrote:
A command is always sent from the CT to the WS and a response is always sent from the WS to the CT. The term command and response no longer dictate the order that the messages are sent, that is, the WS may send a response first and the CT will respond by sending a command.
I think it's just the software engineer being stuck on the English language rather than focusing on the logical aspect of the documentation. Gratuitous network responses are very common in the networking world. [Gratuitous ARP Response](https://wiki.wireshark.org/Gratuitous\_ARP) There are also gratuitous RIP and eBGP responses. Probably a dozen other network protocols supporting gratuitous response messages. That's all I can think of at the moment. Best Wishes, -David Delaune
Randor wrote:
think it's just the software engineer being stuck on the English language rather than focusing on the logical aspect of the documentation
Got it in one. He was stuck on the notion that incoming messages to him were called 'commands', even when they were responses to something he sent, and vice versa.
Software Zen:
delete this; -
quantum communication :omg:
