# Asking Technical Questions CS 3110 Fall 2017 <br/> Prof. Clarkson Last fall, CS 3110 had 2700 Piazza posts. At that volume, there's a tendency for noise to drown out signal. That is, it can be difficult to find answers to your question or to related questions. And there simply aren't enough instructor resources to answer that many questions in the full detail we would like. So I offer this guide in an attempt to help students to improve their skills in asking <i>thoughtful</i> technical questions: questions that are well posed, and that are likely to receive useful answers. This skill will transcend CS 3110 and be useful throughout a career in computer science. Of course, I am not the first person to give some thought to helping people ask better technical questions. The classic guide is by [Raymond and Moen][smart]. It is highly recommended (though 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 or inspired by *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. Complicated problems can't necessarily be solved with a few seconds of googling. Read, sit back, relax, and give the problem some thought before posting on Piazza. It is often obvious to potential answerers when a question has been asked "off the cuff" without any research, and that tends to diminish their enthusiasm for answering. So avoid instantly firing your whole arsenal of questions when your first search turns up no answers, or too many. When you violate this advice for particularly easy to find information, you might receive an answer in the form of a vague pointer: "The answer to that is in the course notes" or "see the assignment writeup." These replies mean that the responder thinks you will learn more if you seek out the information than if you have it fed to you. Try not to be offended by this kind of response; it is helping you become a better question asker. If you truly can't find the information, use the advice below to help you continue in your search for it. ## 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 better the help you are likely to receive. Display the fact that you have done your homework by trying to find the answer first, per the discussion above, and what you have learned from that research. 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 didn'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 method Foo.Bar() - inconsistent precondition (This Bad/Good/Splendid classification is borrowed from Lyn Dupr&eacute;'s splendid book *Bugs in Writing: A Guide to Debugging Your Prose*, a classic and still relevant manual for technical writing in computer science.) Another good convention is to phrase the summary as an actual one-sentence question, then provide a longer-form rephrasing of the question in the body of the post. This works well on sites like Stack Overflow but less well on Piazza, which typically shows only three to five words. * **Bad:** Is this right? * **Good:** Does a monad always have a bind operation? * **Spendid:** Must monad have bind? 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.** 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". 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 pursuing an answer 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 at times 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. 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 fail 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 an answer, avoid immediately bouncing 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? **How to interpret seemingly terse answers.** Sometimes students find answers on Piazza to be terse. Unfortunately, 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. **What if your question is going unanswered for several days?** Unfortunately, at the volume of questions we experienced last year in this course, it's inevitable that instructors will not be able to respond to all questions. But if even other students aren't providing useful answers to your questions, 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. Even better, go to office hours to ask there, and afterwards, do everyone a favor by turning the question into a note with an improved version of the question and a summary of the answer.