If you’re asking somebody to help you, you want to make it easy for them, not harder


A customer liaison asked a question that went roughly like this:

From: Liaison

My customer is having a problem with the header file winfoo.h. The environment is Windows Vista German SP1 with Visual Studio 2008 Professional German SP1 and Windows SDK 6000.0.6000 German. When they try to include the file in their project, they get an error on line 42. "The character ';' was not expected here." Can somebody help?

From: Raymond

Can somebody please attach a copy of the offending file? There are many versions of winfoo.h, and it's not clear which version comes with Visual Studio 2008 Professional German SP1 + Windows SDK 6000.0.6000 German.

I figured that'd be easier than provisioning a new virtual machine, obtaining temporary license keys for all the products, then installing Windows Vista German SP1, Visual Studio 2008 Professional German SP1, and Windows SDK 6000.0.6000 German. All to get one file. A file the customer already has right in front of them. Where all that's really interesting is line 42, and maybe a few lines surrounding it on either side.

Time passes.

The following day, another message arrives from the customer liaison.

From: Liaison

Anyone?

At this point, I engaged my thermonuclear social skills.

From: Raymond

By "somebody", I meant "you".

That went into some people's "Raymond Quotes" file.

Remember, if you're asking somebody to help you, you want to make it easy for them, not harder.

"Hey, Bob, I've got a jar of pickles, and I can't open the lid. Can you help?"

Bob says, "Sure, I'll give it a try."

"Great! The jar is in the storage room in the basement, on the third aisle, top shelf, second from the left."

Bob is now suddenly less interested in helping you open that jar of pickles. Shouldn't you go get the jar of pickles and bring it to him?

Comments (36)
  1. Anonymous says:

    I was expecting to see the Liaison come back with, "I don't see why I should do that." I've had that happen more than once.

  2. RangerFish says:

    We have a standing policy on our team – if a QA raises a bug without the correct logs attached, it WILL get bounced back to them with a comment along the lines "please attach xyz.log which demonstrates this issue". If it comes to a dev again without the logs, it WILL get closed with a comment along the lines of "This QA is an idiot".

    A few bugs got closed like that but the QA boss quickly caught on and started policing his own team.

  3. Anonymous says:

    I'm with the customer here. If you're providing support for a number of products, I would assume that you have quick access to all versions of the products you are supporting.

    The customer is probably not trying to make it hard for you. He just didn't expect that the Windows developers would ask him to send them Windows header files. He probably expected the question to be directed at some internal Microsoft file distribution fairy.

  4. Anonymous says:

    @Sven2

    Note that the customer liaison is not the customer; they are also a Microsoft employee, paid to read the customer query, and ask sensible questions of the developers. It is reasonable for Raymond to say "I don't have that precise file to hand; can you get it for me?" and expect the employee who is paid to interact with the customer to either ask the customer for a copy of the file, or to direct the question at the file distribution fairy and get a copy for Raymond.

  5. Anonymous says:

    Ideally the customer should have thought to include it when raising the question, especially if they didn't already confirm that it happens across multiple machines. A classic way to get a whacky fault from a header file is typing some junk into it by mistake, eg keyboard fumble after looking up a symbol or focus on wrong window when, and with some bad luck the parser may only final barf many lines later.

    But the general point holds – show, don't tell. You have a unique and horrid thing on your machine – show me as much of it as you can, don't tell me what you think you have.

  6. Anonymous says:

    Ony of my customers wote something liek this: "I won't do this, because I have the feeling this will not help solving the problem."

  7. Anonymous says:

    "Hey, Bob, I can't open the lid on a jar of pickles. Can you help?"

    Bob says, "Sure, I'll give it a try."

    "Great! The jar is at the supermarket, on the third aisle, top shelf, second from the left.  Go buy one and open the jar for me."

  8. Anonymous says:

    Raymond is right here, but sadly so is alegrl.

  9. Anonymous says:

    @alegr1: It could be a bug in the installer generator which copied the wrong file when building the localized installer. It could be version skew (the German version could be slightly earlier or slightly later than the "international" (that is, USA) version). And so on. He should at least provide a MD5 of the file so Raymond could check if it is really identical.

    [The header files aren't localized. The problem is that out in the product group, we don't work with the SDK that ships to the public. We generate daily builds of the header files (because we're always working on the next version of Windows, and it's not obvious which daily build became the one that shipped in the SDK. -Raymond]
  10. Anonymous says:

    Sure, header files across locale "should" be identical, but how many times have you come across a situation when debugging a problem where two things that "should" be identical weren't?  When debugging it's always best to assume as little as possible and verify as much as possible to avoid wasting vast amounts of time looking in the wrong places because seomthing that you "knew" to be true turned out not to be.

  11. Anonymous says:

    Raymond's thermonuclear social skills cropped up in his FIRST response as well as his second.  Leading off the question with "Can somebody please attach" was deliberate mocking of the liason's question.  If he'd written merely "Please attach", the liason would not have misunderstood, and would have responded correctly.

  12. Can somebody please attach a copy of the offending file?

    I assume your use of the word "somebody" in this question was a reference to the liaison's use of the word "somebody" in the original request; while this is quite clever it may have gone over their heads.

    If you had worded this as "please ask the customer to pull winfoo.h from the include directory of the SDK as installed on their machine and send it to us" then the ambiguity would have been avoided.

  13. Anonymous says:

    I'm with Raymond.

    That said, it seems like the odds of the Windows SDK actually shipping with a header file containing a typographical error is pretty low.

    On the other hand, more than once I've had to deal with anti-virus software corrupting compiler input files, causing bizarre-yet-persistent syntax errors that make no sense at all (i.e. you go look at the file, and it doesn't say anything like what the compiler is complaining it says).

    In those cases, attaching the file isn't going to help at all, because it's some impossible-to-duplicate confluence of the exact software executing at the precise moment of failure. The file looks fine if you examine using anything other than the exact compiler executable that's having trouble with it.

    But even so…the first step is of course to attach the file that is purported to be faulty. Why should anyone at Microsoft be expected to do anything at all about the supposed problem without actual information?

  14. Anonymous says:

    This is a common problem on Stack Overflow, too. People will paste in their 200 lines of code and ask "Why don't I get the right output when I give 'foo' as the input?", apparently with the expectation that we will create a scratch project, copy their code into a source file, compile it, run it, give 'foo' as the input, analyze the output, and determine what's wrong with it.

    They don't understand that only people with their compiler handy can help them, whereas if they actually just explained what the program was doing wrong, anybody who understood programming would be able to help them.

    In Raymond's case, I probably would have said something like "I don't know the answer, but if you attach the version of winfoo.h the customer is compiling with, I'll be glad to look into it for you."

  15. Anonymous says:

    Given that no-one else has reported this problem, it is actually Quite Likely that the customer's version of winfoo.h is not what Raymond would end up with if he installed the products in question. Asking for the actual file from the actual customer is the only sane option.

  16. Anonymous says:

    Asking "somebody" is like playing to the middle when you play doubles in tennis.

  17. Anonymous says:

    Even when paying them, ms own employees doesn't want to touch hyperv.

  18. Anonymous says:

    @Gabe:

    If you provide to much context (more than one code line), people doesn't want to help you because "It's to much code to fathom".

    If you provide to little context (less than a million sloc), people complain that there's a work-a-round for the trivial example.

  19. Anonymous says:

    Your social skills of a thermonuclear device went into action when you asked for "somebody" to attach the file.  That's at best passive-aggressive, and at worst just plain confusing.  I find it hypocritical that you seem to value clarity and pragmatism in communcation from others, while not providing it yourself.

    [By "somebody" I meant "the customer or the liaison or another person in the Developer Support team with access to the relevant files." -Raymond]
  20. Anonymous says:

    @pete.d: You may think that the SDK headers have no typographical errors.  I simply refer you to connect.microsoft.com/…/-pragma-deprecate-in-vc-headers-should-be-deprecated-with-a-final-d

    The engineers triaging bugs on Microsoft Connect also have the social skills of a thermonuclear device, combined with a skewed view of the world.  A header file is not part of a released Windows Product, it was placed on my computer by the Visual Studio installer.  The fact that the header file may have been provided to the DevTools team by the Windows team is of little import to a customer — teams within Microsoft should take responsibility for what they ship, and shield the customer from blame shifting between MS departments.

    (Almost) every other bug tracking system in the world has an "Assigned To" field so that a triage engineer can get the right team to address it.  Beats me why Microsoft would choose not to.

  21. ta.speot.is says:

    I wouldn't mind knowing what the underlying problem was. My guess is a macro with a generic name that's being unexpectedly substituted throughout the header file.

  22. Anonymous says:

    It took me a long time but I eventually learned to never use the word "somebody" but rather to explicitly point out individuals — even if more than one person really could do it.  This is also relevant when sending emails: Including a single recipient often produces much better results than including a dozen recipients.

  23. Anonymous says:

    @Ben Voigt: They do have an Assigned To. You just can't see it from your perspective.

    Now then, that brings up a larger issue. No &%$#D@ way of filing bugs against the Windows core components, even when the bugs are obvious.

  24. "Can somebody please attach a copy of the offending file? … [plus unproductive commentary on the vaguaries of life]"

    Answer: Yes.  Somebody can.  But since Nobody has been asked to (only whether or not they can) then it is unlikely that Anybody will.

    imho The correct response should have been something along the lines of:

    "It is highly unlikely that the winfoo.h in the normal distribution of the products involved would contain this error, so the most likely explanation is that the customer's winfoo.h has become corrupt or been modified.  However, to rule this out we require a copy of the customer's winfoo.h.  Without that we cannot progress this issue."

    That contains the required information (what is needed and why) along with a statement of the implications (nothing is going to happen on this unless some condition is met – i.e. the provision of winfoo.h).  It has all the presence and effectivenesss of an armed and fuelled thermonuclear delivery device without actually having to hit The Red Button to launch it.

    Is this what was meant in the "Can somebody .. ?" response.  Yes.  But we tend to forget that people tend to what what they are asked to do, not what we think we have asked them to do.

    Speculating as to how things might have played out ….

    Upon receiving this response Liaison should have either a) realised that they should have attached the file that the customer had provided but which they erroneously  thought wasn't necessary to pass on to Development or b) if the customer had not already sent that file, then understood that they needed to go back to the customer to request it, and in the process provide the initial feedback from development.

    There is a real possibility that the customer might then have responded with "Oh, good point.  We had some codegen utilities or other processes that might have modified this file accidentally – we'll check those first ourselves"

    [Actually, a possibility is that the customer has set some wacky combination of #defines that the header file doesn't take into account. For example, they may have set NONAMELESSUNION. The point was "We need to see what's on line 42 so we can figure out what could possibly cause the compiler to barf there. -Raymond]
  25. alegr1 says:

    On the other hand, the include files in the SDK *SHOULD* *NOT* *BE* *LOCALIZABLE*.

    If you ship different source/include files for different locales, you're doing it wrong.

    The same set of source files compiled by any language version of SDK/DDK/Visual Studio MUST compile/not compile the same way and produce the same binaries, modulo the timestamp and the checksum.

  26. Anonymous says:

    I work for a company developing embedded software (so VS is not our primary tool…). We KNOW what debugging is like, we know what it takes to pinpoint a problem.

    It is not for bragging I tell this: A while ago, not long before Christmas (so we received it as a Christmas gift) one of the main support guys in the company developing our compiler tools sent us an email, on his own accord, telling that we are his favorite customer: Our bug reports are detailed, yet terse, to the point, and with all the required information to pinpoint the problem.

    I guess he is right. I have been responsible for several of those reports. Preparing them has taken two, maybe three, maybe more, full days of work, to narrow down the set of possible causes, simplifying the case, describing in detail for the suppport guy how to reproduce the problem.

    To repeat: We do not do this for bragging; we do it of pure self-interest. We know that if WE spend one DAY extra on pinpointing what is wrong (after all: we have full control over the situation where the problem occurs), we will probably receive a workaround or a cure one WEEK earlier. Maybe two weeks. Maybe a month We spend a couple man-days extra on preparing the report, and in return, sometimes twelve to fifteen programmers can move ahead one WEEK earlier. The extra effort pays back tremendously!

    This really ought to be obvious to every software developer in the world. So stories like the one Raymond tells should never need to refer to people of our profession. Ideally, that is. Yet, this support guy felt a desire to tell us that we make error reports the way all of us should do. So mayhe the ideal doesn't always correspond to reality :-).

    Well, we certainly did appreciate his Christmas letter; there is no reason to keep that hidden! We have spent those resources, at several occasions, and it has paid back – not only budget-wise, but also in human relations. Several times, when chatting with other software people outside our company, I have promoted this: When you report a software bug, strive to be the support guy's favorite customer. You KNOW what it takes; it's your job! So go ahead, do it! Amateurs may not know how we work, they are excused. But WE know. Show it, when you report bugs to the support guys!

  27. cheong00 says:

    On somewhat unrelated note, I remember a bug cased by Chinese character caused the source control to break… a few labelled versions contains only the label and that version of source is not retrievable. Eventally the company banned the use of Chinese in all future versions of source code (except the string resource table).

  28. Anonymous says:

    @Joylon

    "Yes.  Somebody can.  But since Nobody has been asked to…"

    That's a classic children's game you're playing there:

    Mum: "Can you wash the dishes, Billy?"

    Billy: "I am capable of doing that, yes"

    The difference is that the child is trying to get out of doing something. Here, the customer liason is getting assistance with an issue they're responsible for getting sorted out. It's in their interest to do what is asked. And I certainly don't buy the argument that they didn't understand that they should have done. This is a Microsoft employee. They should understand what is required to look into a problem like this, and they should also understand that the tech helping them is a valuable commodity who's time they should not be wasting.

    Your speculation is exactly as it should have played out. In fact, it should never have gotten that far. If I was working triage on an issue where line 42 is causing a compiler I sure as heck know what my first question would be… "What's on line 42?".

  29. Anonymous says:

    Based on, "If you're asking somebody to help you, you want to make it easy for them, not harder", then I think one would have to agree that providing the header would ease the task (and probably a simple project that includes the header and build log showing the error). And that the best person to obtain this is also the person asking for help.

    Anyways, I find the reaction entertaining. Sometimes one can be lazy about these things by asking (for example) someone you know is a pickle junkie to help… he'll go out of his way to get a hot dill fix. This wasn't one of those times.

  30. Anonymous says:

    Regarding Localization: Presumably header files are not localized. However, the customer didn't know that, so they helpfully tried to include whichever info they believe is relevant, including the fact that their version of Windows/VS/etc. is German. The support person should know whether this detail is relevant or not.

  31. @Raymond, yes of course that is a possibility.  Identifying additional possibilities doesn't preclude the existing ones, but when helping people to help themselves by sharing all relevant information it can often help to return the favour by sharing what /you/ already think or know.  That can often help the other person come to a realisation of something they had previously overlooked, all on their own.

    (In which case such a post would have become one of those that ended with "We never heard back")  :)

    It's also important to investigate the real bug, which is why reproducible test cases should *always* come from the customer.  Trying to recreate a test case in blissful isolation is a waste of time.  If you succeed then you just spent time recreating what the customer already had.  If you fail then it proves nothing because you cannot be sure that what you recreated is actually a perfect model of the customer's problem, so you still have to go back and ask for the test case.

    In our case (middleware software), because such test cases are usually highly complex and contain a large number of variables and external systems which often aren't relevant to the bug, we further stipulate that the test case should be reduced to the simplest possible scenario that demonstrates the problem.

  32. cheong00 says:

    @Jonathan: Hey, you're assuming the staffs working at customer liason know the product.

    While some of them do, in my experience most of them have "user" level of knowledge of the software they're supporting (i.e.: they themselve don't necessary know more than us). What they're required to do is to search in their knowledge base, hoping there is similar problem recorded there, and esculate to supervisors or even engineers if they're unable to handle the problem.

    Their knowledge base don't necessary have information on which part of VS installation is NOT localized. So I'm not surprised if some of them do not know this.

  33. Anonymous says:

    @pete.d Not sure whether you could class it as a typo but VC2005's intrin.h misdeclared _interlockedbittestand[re]set (the volatile keyword was accidentally omitted from the first parameter). [Fixed in VC2008.]

  34. Anonymous says:

    Jolyon Smith: Even if you do manage to reproduce the customer's problem, you still don't know if you actually reproduced the SAME problem. Maybe you figured out how to get that error on line 42, but there's no telling how many ways to get that same error. Who's to say you did the same thing to get that error?

  35. In c:Program Files (x86)Microsoft Visual Studio 10.0vcatlmfcincludeafxwinforms.inl, we had to change

    extern "C" void   AfxmEnsureManagedInitialization();

    to

    extern "C" void  __cdecl AfxmEnsureManagedInitialization();

  36. alexcohn says:

    I wonder, did the liason refer to Raymond's response, or to their own original question?

    More often than not, e-mails chain the replies. Usually it's OK to drop this duplicate text when quoting; but here, this context is important.

    Actually, the situation is somewhat similar to the original question.

Comments are closed.