# Asking Thoughtful Questions CS 5430 Spring 2017 Prof. Clarkson The classic guide to how to ask technical questions is by [Raymond and Moen][smart]. It is highly recommended (though perhaps acerbic) reading! Here, I summarize some of its main points and interpret them in light of this course. *Acknowledgement: nearly all the prose in this document is excerpted from Raymond and Moen. They deserve any credit; Clarkson deserves any blame.* [smart]: http://www.catb.org/~esr/faqs/smart-questions.html ## Before Asking **Try to find the answer.** Search Piazza, the web, or a manual. Google and the Find function (probably Ctrl-F) in your browser are your ally. Read the course notes, slides, handouts, and textbooks. Do some experiments with whatever software you're using. Read any available, relevant source code. Take your time. Do not expect to be able to solve a complicated problem with a few seconds of googling. Read, sit back, relax, and give the problem some thought before posting on Piazza. Trust me, the instructors (and many of your peers) will be able to tell from your questions how much reading and thinking you did, and will be more willing to help if you come prepared. Don't instantly fire your whole arsenal of questions just because your first search turned up no answers (or too many). When you violate this advice for particularly easy to find information, you're likely to receive an answer in the form of a vague pointer: "The answer to that is in the course notes" or "See the assignment writeup". Often, the person telling you this has the web page with the information you need open, and is looking at it as they type. These replies mean that the responder thinks you will learn more if you seek out the information than if you have it spoon-fed to you. You shouldn't be offended by this kind of response; it is helping you become a better question asker. ## When Asking **Prepare your question.** Think it through. Hastily-asked questions tend to get hastily-written answers, or none at all. The more you do to demonstrate that you have put thought and effort into solving your problem before seeking help, the more likely you are to actually get help. Display the fact that you have done your homework by trying to find the answer first, per the discussion of that above; this will help establish that you're not wasting the time of your fellow students or the instructors. Better yet, display what you have learned from doing these things. Instructors like answering questions for people who have demonstrated they can learn from the answers. Even saying "I googled on the following phrase but didn't get anything that looked promising" is a good thing to do when requesting help, if only because it records what searches won't help. **Summarize carefully.** Put careful thought into what Piazza calls the "Summary" of your question, or what in an email might be called the "Subject." The summary is your golden opportunity to attract attention in around 50 characters or fewer. (Although Piazza allows up to 100, shorter is better.) Don't waste your space on fluff like "Please help me" (let alone "PLEASE HELP ME!!!!"; messages with summaries like that get ignored by reflex). Don't try to impress others with the depth of your anguish; use the space for a super-concise problem description instead. One good convention for summaries, used by many tech support organizations, is "object - deviation". The "object" part specifies what thing or group of things is having a problem, and the "deviation" part describes the deviation from expected behavior. The process of writing an "object - deviation" description will help you organize your thinking about the problem in more detail. * **Bad:** HELP! A1 issues * **Good:** A1 - specification broken * **Splendid:** A1 release code method Foo.Bar() - spec inconsistent about precondition Imagine looking at the left-hand pane of Piazza, with just the summaries showing. Make your summary reflect your question well enough that the next student searching with a question similar to yours will instantly recognize your post as being related to their question, so that they won't need to post the question again. **Focus your question.** Open-ended questions tend to be perceived as open-ended time sinks. You are more likely to get a useful answer if you are explicit about what you want respondents to do. This will focus their effort. Think of expertise as an abundant resource and time as a scarce one. The less of a time commitment you implicitly ask for, the more likely you are to get an answer from someone really good and really busy, whether that's a fellow student, a TA, or the professor. So it is useful to frame your question to minimize the time commitment required for an expert to field it. * **Bad:** Would you explain snarks again? * **Good:** Would you give me a pointer to a good place to start reading about snarks? * **Splendid:** I've googled for snarks, read the Wikipedia article on them [url], as well as the paper cited as [5] there, which seems to be the main source for the article. But I'm confused about what it means by "mixing" and the paper it cites for that [url] is behind a paywall. Can you point me to a place where I can read more about "mixing"? **Write in clear, grammatical, correctly-spelled language.** Spend the extra effort to polish your language. It doesn't have to be stiff or formal. In fact, I enjoy informal, slangy, and humorous language used with precision. Spell, punctuate, and capitalize correctly. Don't TYPE IN ALL CAPS; this is read as shouting and considered rude. Don't use instant-messaging shortcuts and acronyms such as "u" or "lol", unless it is with calculated irony. Never, ever flag your question as "Urgent" and especially not "URGENT". Doing so runs the risk of being perceived as selfishly attempting to elicit immediate and special attention. A well-written question is more likely to receive that attention than a so-called "urgent" question. Courtesy never hurts, and sometimes helps. Use "Please" and "Thanks". Make it clear you appreciate the time people spend helping you for free (if they are fellow students) or outside their scheduled office hours (if they are instructors). To be honest, this isn't as important as being grammatical, clear, and precise. But if you've got the rest of your ducks in a row, politeness does increase your chances of getting a quick and useful answer. This advice especially applies to the main question. Sometimes a follow-up thread will proceed casually, and that can be okay. But if your follow-up is still attempting to pursue a quest for knowledge related to the original question, keep it linguistically shiny. **Use plain text as much as possible.** Piazza offers many formatting options, which can be used for better or for worse. Bold face, bullets, and headings can all be useful for conveying structure in longer questions. Unfortunately, the rich text editor has been rather buggy recently with respect to preformatted text and code blocks. If you take the time to use these features, also take the time to re-read your post to make sure they are being rendered in the way you intended. Screenshots are useful supplements to a post but should never be the primary content. The contents of them are not searchable and might be difficult to read on the viewer's device. Make sure to clearly prepare your question in descriptive text first, then provide the screenshot purely as augmentation. **For tech support, skip Piazza altogether.** Remote tech support is always a poor substitute for one-on-one problem solving. Come to office hours instead. **Don't rush to claim that you have found an error.** When you are having problems with an assignment, don't claim you have found an error in it unless you are sure of your ground. It's especially undiplomatic to yell "error" in the summary line of your post. Remember, there are many other students that are not experiencing your problem—otherwise you would have learned about it while searching Piazza. So when asking your question, it is best to write as though you assume you are doing something wrong, even if you are privately pretty sure you are right. If there really is an error, you will hear about it in the answer. Play it so the instructors will want to apologize to you if the error is real, rather than so that you will owe them an apology if you have messed up. It's also best to construct your question with what you think the fix to the error is, or at least a candidate for that fix. For example, if you think a sentence in an assignment is in error, you should provide the original sentence and what you believe to be a corrected version of it. The above discussion applies to slides and notes, too, but I freely admit that the probability of errors on those materials is much higher than the probability of errors on assignments, which are vetted quite closely. I certainly want to fix any errors in the slides and notes, so please do not hesitate to write a post suggesting corrections. When it comes to small typos, if they are of a technical nature I'll certainly fix them, but do forgive me if in the rush of the semester I forget to fix smal misspellings. * **Bad:** BUG in A1?! That `41` can't be right lol. * **Good:** On Problem 2 of A1, I think the `41` is wrong. * **Splendid:** On Problem 2 of A1, I tried completing the problem with the `41` that is given as a sample input, but I got an answer that is nonsensical (and that I won't post here because of AI concerns). Can you suggest where I read more about the material behind this problem, so that I can figure out what I'm doing wrong? * **Amazing:** On problem 2 of A1, it gives a sample run of `answer(life, universe, everything)` and says the output should be `41`. I noticed that's inconsistent with the writings of Douglas Adams that we studied this week. In the course notes [url] it says `42` instead. I was just wondering whether that inconsistency was deliberate or not. Thanks! ## After Asking **How to respond to an answer you don't understand.** If you don't understand the answer, do not immediately bounce back a demand for clarification. Use the same tools that you used to try and answer your original question (Piazza, the web, a manual, Google, course notes, slides, handouts, textbooks, etc.) to understand the answer. Then, if you still need to ask for clarification, exhibit what you have learned. For example, suppose you receive the answer, "It sounds like you've got a stuck zentry; you'll need to clear it." * **Bad followup:** What's a zentry? * **Good followup:** Thanks! I read the man page, and zentries are only mentioned under the -z and -p switches. Neither of them says anything about clearing zentries. Is it one of these or am I missing something here? **What if your question is going unanswered for several days?** Don't take it personally. No response is not the same as being ignored, though admittedly it's hard to spot the difference from outside. Simply re-posting your original question is a bad idea. There is some reason your question isn't being answered. So go back to the advice above. Figure out how to improve your question, then edit or retract the original. Ask a thoughtful question instead. Or go to office hours to ask there; afterwards, do everyone a favor and turn the question into a note with an improved version of the question (if needed) and a summary of the answer. **How to interpret seemingly terse answers.** Sometimes students find answers, either from other students or from instructors, on Piazza to be terse, gruff, or salty. The underlying problem is most likely time, not intent. Your fellow students and your instructors rarely have the time to write a gushing, emotionally effusive response. Efficiency demands terse writing. So, as an answer seeker, please don't confuse terseness with hostility. And as an answer giver, don't cloak hostility in terseness: be respectful, and give your peers the benefit of the doubt.