{"id":13296642,"url":"https://github.com/shlomif/writing-the-perfect-question","last_synced_at":"2026-01-24T02:01:35.041Z","repository":{"id":66240546,"uuid":"152085324","full_name":"shlomif/writing-the-perfect-question","owner":"shlomif","description":"Jon Skeet's Writing the Perfect Question","archived":false,"fork":false,"pushed_at":"2020-04-01T07:26:56.000Z","size":21,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-14T22:46:45.602Z","etag":null,"topics":["asciidoc","creative-commons","hacktoberfest","help","jonskeet","questions","stackoverflow","stackoverflow-questions","tech"],"latest_commit_sha":null,"homepage":"https://codeblog.jonskeet.uk/2010/08/29/writing-the-perfect-question/","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shlomif.png","metadata":{"files":{"readme":"README.asciidoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-08T13:32:13.000Z","updated_at":"2021-10-21T06:59:26.000Z","dependencies_parsed_at":"2023-05-22T07:45:25.881Z","dependency_job_id":null,"html_url":"https://github.com/shlomif/writing-the-perfect-question","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shlomif%2Fwriting-the-perfect-question","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shlomif%2Fwriting-the-perfect-question/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shlomif%2Fwriting-the-perfect-question/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shlomif%2Fwriting-the-perfect-question/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shlomif","download_url":"https://codeload.github.com/shlomif/writing-the-perfect-question/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248975299,"owners_count":21192199,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asciidoc","creative-commons","hacktoberfest","help","jonskeet","questions","stackoverflow","stackoverflow-questions","tech"],"created_at":"2024-07-29T17:20:53.915Z","updated_at":"2026-01-24T02:01:30.021Z","avatar_url":"https://github.com/shlomif.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"Writing the Perfect Question\n============================\nJon Skeet https://codeblog.jonskeet.uk/\n:Date: 2018-10-08\n:Revision: $Id$\n\n*Please note: this blog post is _not_ a suitable place to post a\ndevelopment question.* You should probably be doing that on\nhttp://stackoverflow.com/[Stack Overflow] – after reading this post, of\ncourse. I’ve received a truly astonishing number of comments on this\npost which are basically misplaced questions. Such comments are simply\nmarked as spam – they don’t belong here.\n\nTL;DR: If you don’t have time to read this post fully, I have a\nhttps://tinyurl.com/stack-checklist[checklist version]. I’d strongly\nencourage you to read this post fully though, when you have time.\n\nI’ve added a tinyurl to this post for easy reference: +\nhttp://tinyurl.com/stack-hints. Nice and easy to remember :)\n\n'''''\n\nA while ago, I wrote a\nhttps://codeblog.jonskeet.uk/2009/02/17/answering-technical-questions-helpfully[blog\nentry] on how to _answer_ questions helpfully on sites like\nhttp://stackoverflow.com/[Stack Overflow]. Recently I saw\nhttp://meta.stackoverflow.com/questions/59991[a meta question about bad\nquestions] and thought it would be worth following up with another blog\npost on _asking_ questions. For the sake of convenience – and as Stack\nOverflow is so popular – I will assume the question is going to be asked\non Stack Overflow or a similar Stack Exchange site. Most of the post\ndoesn’t actually depend on that, but if you’re asking elsewhere you may\nneed to tweak the advice a little.\n\nThere are plenty of similar resources around, of course – in particular,\nhttp://catb.org/esr/faqs/smart-questions.html[How to Ask Questions the\nSmart Way] by Eric Raymond and Rick Moen is a perennial favourite.\nStill, I think I can bring something to the table.\n\n[id=\"golden-rule\"]\nThe Golden Rule: Imagine You’re Trying To Answer The Question\n-------------------------------------------------------------\n\nIf you don’t remember anything else from this post, remember this bit.\nEverything else follows from here. (And yes, this does smack somewhat of\nhttp://www.biblegateway.com/passage/?search=Matthew+7:12\u0026version=NIV[Matthew\n7:12].)\n\nOnce you’ve finished writing your question, read it through. Imagine you\nwere coming to it fresh, with no context other than what’s on the\nscreen. Does it make sense? Is it clear what’s being asked? Is it easy\nto read and understand? Are there any obvious areas you’d need to ask\nabout before providing an answer? You can _usually_ do this pretty well\nhowever stuck you are on the actual question. Just apply common sense.\nIf there’s anything wrong with the question when _you’re_ reading it,\nobviously that will be a problem for whoever’s actually trying to answer\nit. So fix the problems. Improve the question until you can read it and\nthink, “If I only knew the answer to the question, it would be a\npleasure to provide that answer.” At that point, post and wait for the\nanswers to come rolling in.\n\n______________________________________________________________________\nObviously this is somewhat easier to do if you have a certain amount of\nexperience answering questions, particularly on the forum where you’re\nabout to post. So, what should you be looking out for?\n______________________________________________________________________\n\n[id=\"title\"]\nQuestion title\n--------------\n\nWhen a reader first sees your question, they’re likely to be scrolling\ndown a list of snippets. The most eye-catching part of the snippet will\nbe the title – so use that text wisely. While you _can_ include language\nor platform information, you should only do so naturally – not as a sort\nof “header”. For example, this is bad:\n\n___________________________\nJava: Why are bytes signed?\n___________________________\n\nBut this is okay:\n\n_____________________________\nWhy are bytes signed in Java?\n_____________________________\n\nOf course, you should _also_ include this information in tags, as it\nwill help people who pay particular attention to specific tags.\n\nIdeally, a question title should be a question – but frankly that’s not\nalways feasible. I would recommend favouring a short, descriptive title\nwhich captures the theme of the question without actually _being_ a\nquestion instead of really trying to crowbar it into the form of a\nquestion when it really doesn’t want to be. That’s not an excuse for\nlaziness though – it’s _usually_ possible to come up with a good title\nwhich is genuinely a question.\n\nIt’s important that the question title is _specific_ though, and has at\nleast some meaning with no other information. A question such as “Why\ndoesn’t this work?” makes absolutely _no_ sense without the rest of the\nquestion. Likewise a “question” title of “Please help” is unlikely to do\nwell.\n\n[[context]]\nContext\n-------\n\nIn most cases, anyone answering the question will need to know what\nlanguage and platform you’re using. The basics should usually be\ncommunicated through tags, but it may very well be worth providing more\ninformation:\n\n* Language version (e.g. C# 4)\n* Platform version (e.g. .NET 3.5; note that this isn’t always implicit\nfrom the language version, or vice versa)\n* Operating system, if it could be relevant (e.g. particular permissions\nissues)\n* Any other relevant software (e.g. database type and version, the IDE\nyou’re using, web server you’re connecting to)\n* Any other constraints. This is particularly important. It’s _really\nannoying_ to give a perfectly good answer to a question, only to be told\nthat you’re not allowed to use feature X or Y which provide the obvious\nsolution.\n** If you have unusual constraints, it’s worth explaining why. Not only\ndoes this answer the obvious follow-up comment, but it also gives more\ninformation about what _other_ solutions may not be applicable.\n\nDescribe what you’ve already tried and the results of any research. (You\n_have_ searched for a solution to your problem before asking it, haven’t\nyou? Stack Overflow isn’t meant to replace basic search skills.) Often\nthere will be other people in a similar situation, but the answers\ndidn’t quite match your situation. Just like the above point about\nunusual constraints, it saves time if you can point out differences\nbetween your situation and other common ones. It’s even worth referring\nto other related questions explicitly – particularly if they’re on the\nsame forum. Aside from anything else, this shows a certain amount of\n“due diligence” – people are generally more willing to help you if can\nshow you’ve already put some effort in.\n\nYou should absolutely make sure that you tag the question appropriately.\nIf you’re not sure which exact tags are appropriate, see what gets\nauto-suggested and look at samples for each one. If that sounds like a\nlot of work, just remember how much time you may be able to save\nyourself in the long run. It gets easier over time, of course.\n\n[[problem-statement]]\nProblem statement\n-----------------\n\nMake sure it’s obvious what you’re trying to get out of the question.\nToo many “questions” are actually just statements: when I do X,\nsomething goes wrong.\n\nWell, what did you expect it to do? What are you trying to accomplish?\nWhat have you already tried? What happened in those attempts? Be\ndetailed: in particular, if something didn’t work, don’t just state\nthat: tell us _how_ it failed. If it threw an exception, what was the\nexception? (Don’t just give the type – give the error message and say\nwhich line threw it. If there’s a nested exception, post that too.)\n\nIf at all possible, write a sort of “executive summary” at the start of\nyour question, followed by a more detailed description. Remember that on\nthe list of questions, the first few sentences will appear as a snippet.\nIf you can get a sense of the question across in that snippet, you’re\nmore likely to attract views from people who can answer the question.\n\nOne trap that many posters fall into is to ask how to achieve some\n“small” aim, but never say what the larger aim is. Often the smaller aim\nis either impossible or rarely a good idea – instead, a different\napproach is needed. Again, if you provide more context when writing your\nproblem statement, we can suggest better designs. It’s fine to specify\nhow you’re currently trying to solve your bigger problem, of course –\nthat’s likely to be necessary detail – but include the bigger goal too.\n\n[[code]]\nSample code and data\n--------------------\n\nI may be biased on this one. I’m a _huge_ believer in sample code, both\nfor questions and answers… and I probably use it in an unconventional\nway. I usually paste it into a text editor, and try to compile it from\nthe command line. If that’s not likely to work (and the problem isn’t\nobvious by inspection), I’m unlikely to bother too much with it. Firing\nup Eclipse or Visual Studio and finding an existing project I don’t care\nabout or starting a new one is going to take much more time.\n\nThat means if you want _me_ to look at code, it should:\n\n* Be standalone. Don’t try to talk to a database unless you really have\nto. (Obviously for database questions, that’s kinda hard :) If you use\nsample XML, provide a short but _complete_ XML file for us to reproduce\nthe issue with. (And the same for other file types, obviously.)\n* Be complete. If there are missing imports or using directives, that’s\nreally annoying\n* Actually compile (unless the compilation error is the reason for the\nquestion). Don’t give me code which is “something like” the real code\nbut which clearly _isn’t_ the real code, and may well not exhibit the\nsame symptoms by the time I’ve fixed it so that it compiles.\n* Ideally not bring up a UI. Unless your code is _about_ a UI issue,\ndon’t bring one up. Console apps are simpler, and simplicity is a huge\nbenefit when trying to hunt down a problem.\n* Demonstrate the problem. You should be able to say, “I expected the\nresult to be X, it’s actually Y.” (You should actually say that too, so\nthat we can check that we get the same results.)\n* Be as short as possible. If I have to wade through hundreds of lines\nof code to find the problem, I’m doing work that _you_ should be doing.\nOften if you work hard to reduce the problem to a short but complete\nprogram, you’ll find the issue yourself. You can absolutely do this\nwithout knowing what the problem is; you should be looking to the\ncommunity for their expertise, not their willingness to spend time on\nyour problem doing the work that you can do yourself.\n\nYes, this is a relatively onerous list. It doesn’t all apply to every\nproblem, but it _does_ apply in a great many situations. While I get put\noff by reams of irrelevant, badly formatted code, some of which clearly\nwon’t compile, the inverse is true as well: if I can tell by looking at\nthe question that the code can go through a copy/paste/compile/run cycle\nreally quickly, I’m _much_ more likely to pay the question significant\nattention.\n\nIn data-oriented questions, it’s very often helpful to give some sample\ndata. Cut out anything irrelevant (if your real table has 50 columns,\nyou only need to include relevant ones) but make sure that you give\nenough sample input for it to be meaningful. For example, if you’re\ntrying to group some data by a PersonID column, it’s pretty useless if\nthere’s only one PersonID given, or if each PersonID only appears once.\nIf you _are_ giving examples of expected input and corresponding output,\nmake sure it’s clear _why_ that’s the expected output. Often I see\nquestions which give a small number of samples, and there are various\nways they could be interpreted. This is one area where it’s particularly\nimportant to reread the question from a stranger’s point of view: while\na brief summary of the desired results may well make sense to someone\nwho already knows what your app is trying to achieve, it may be\ngobbledygook to those trying to answer your question.\n\n[[presentation]]\nSpelling, grammar and formatting\n--------------------------------\n\nI know not everyone speaks English natively. My own command of\nnon-English languages is lamentably poor – I’m incredibly lucky that my\nnative tongue happens to be the lingua franca of the technical world.\nHowever, if you’re trying to communicate on an English-language forum,\nyou owe it to yourself to make an effort to write at least _reasonably_\ncorrect English.\n\n* Please use capital letters where appropriate. It really can make a big\ndifference in the readability of text.\n* Please split your text into paragraphs. Imagine this blog post as one\nbig paragraph – it would be almost impossible to read.\n* Please write actual words. There are undoubtedly some abbreviations\nwhich are acceptable to most readers – IMO, IIRC etc –  there’s no\nreason to switch into text-speak with “gr8”, “bcoz”, “u” and so forth.\nIt’s unlikely that you’re _actually_ writing your question on a phone\nwith only a primitive keyboard; show your readers respect by writing\nproperly. It may take you a few more seconds, but if it means you get an\nanswer quicker, it’s surely worth the extra effort.\n* Most browsers have built-in spelling checkers these days, or at least\nhave plug-ins or extensions available to check your text. Technical text\noften creates a lot of false positives for checkers, but if your\nspelling isn’t generally great, it’s worth looking at the suggestions.\n\nHaving said all of this, you’re not trying to create a literary\nmasterpiece. You’re trying to communicate your question as effectively\nas possible. If you’re faced with the choice between an unambiguous but\nugly sentence, or a phrase which stirs the soul but leaves the reader\nconfused about exactly what you mean, go for the unambiguous option\nevery time.\n\nOne way a huge number of questions can be improved with very little\neffort is simply formatting them properly. Stack Overflow’s markdown\neditor is very good – the preview below your input box is almost always\naccurate in terms of the eventual result, and you can always edit the\nquestion later if anything doesn’t quite work. The exact details of the\nmarkdown is beyond the scope of this article – Stack Overflow has a\nhttp://stackoverflow.com/editing-help[detailed guide] though – if you’re\nnew to the site, I’d recommend you at least skim through it.\n\nBy far the most important kind of formatting is making code look like\ncode. Within a text paragraph, simply surround the code with backticks\n`\\`like this\\``. For blocks of code, just indent everything by four\nspaces. If you’re cutting and pasting code, it may already be indented\n(for example if you’re copying code within a class) but if not, the\neasiest way to indent everything is to paste it, select the whole code\nblock, and then press Ctrl-K or the “\\{ }” button just above the editor.\n\nOne of the important things about code formatting is that it means angle\nbrackets (and some other symbols) are preserved instead of being\nswallowed by the markdown formatter. In some cases this can mean all the\ndifference between a question which is easy to answer and one which\ndoesn’t make any sense, particularly in terms of generics in Java and C#\nor templates in C++. For example, like this\n\n_______________________________________________________________________\nWhy can’t I convert an expression of type List\u003cstring\u003e to List\u003cobject\u003e?\n_______________________________________________________________________\n\nmakes no sense at all if the type arguments are removed:\n\n_______________________________________________________\nWhy can’t I convert an expression of type List to List?\n_______________________________________________________\n\nOften experienced members of the site will recognise what’s going on and\nedit your question for you, but obviously it’s better if they don’t have\nto.\n\n[[impressions]]\nMaking a good impression\n------------------------\n\nLeaving aside the main body of the question, there are a few simple ways\nto get the community “on your side” and therefore more likely to give\nyou a useful answer quickly.\n\n* Register as a user and give yourself a meaningful name. It doesn’t\nhave to be your real name, but frankly names like “Top Coder” or “Coding\nGuru” look pretty silly when you’re asking a question which others find\nsimple. That’s still better than leaving yourself as “user154232” or\nwhatever identifier is assigned to you by default though. Aside from\nanything else, it shows a certain amount of commitment to the question\nand/or site: if you’ve bothered to give yourself a name, you’re less\nlikely to be an “ask-and-run” questioner.\n* Keep an eye on your question. There may well be requests for\nclarification – and of course, answers! If you receive an answer which\nwasn’t quite what you were looking for, explain carefully (and politely)\nwhy it’s not suitable for your purposes. Consider going back and editing\nyour question to make it clearer for subsequent users.\n* Don’t add your own answer unless it really _is_ an answer. Often users\nadd extra details in an “answer” when they should really have just\nedited their question. Likewise editing your question is generally a\nbetter idea than adding a long comment to an existing answer –\nparticularly if that comment contains a block of code (which won’t work\nwell in a comment). If you do change the question in response to an\nanswer though, it’s worth adding a comment to the answer just to let the\nuser know that you’ve updated it though… you may well find they quickly\nedit their answer to match the revised question.\n* There’s no need to include greetings and sign-offs such as “Hi\neveryone!” and “Thanks – hope to get an answer soon” in the question.\nThese will often be edited out by other users, as they’re basically a\ndistraction. Greetings at the start of a question are particularly\nuseless as they can take up valuable space in the snippet displayed in\nthe question list.\n* Above all, be polite. Remember that no-one is getting paid to answer\nyour question. Users are giving up their time to help you – so please be\nappreciative of that. If you’re asking a homework question, explain why\nyou’re asking for help with something that traditionally you’d have to\nanswer all by yourself. If a user suggests that your general approach is\nwrong and that there’s a better way of doing things, don’t take it\npersonally: they’re trying to help you improve your code. By all means\ndisagree robustly, but don’t start into ad hominem arguments. (This\nadvice applies to answerers as well, of course.)\n* (Somewhat specific to Stack Overflow.) If an answer is particularly\nhelpful or solves your problem, accept it by clicking on the tick mark\nby it. This gives extra credit to the person who provided that answer,\nas well as giving more information to future readers.\n\n[[conclusion]]\nConclusion and feedback\n-----------------------\n\nStack Overflow is an amazing resource (along with other Q\u0026A sites, of\ncourse). The idea that you can get a good answer to a wide range of\nquestions within _minutes_ is pretty staggering… but there’s an obvious\ncorrelation between the quality of a question and the likelihood that\nyou’ll get quick, helpful answers. Put that extra bit of effort in\nyourself, and it will probably pay for itself very quickly.\n\nI’m hoping to keep this blog post up to date with suggestions received –\nif I’ve missed out anything, over- or under-emphasized a specific point,\nor generally gone off track, let me know either in the comments here or\nmail me (skeet@pobox.com). If this document ends up elsewhere, then that\ncopy may end up being the “canonical” one which is edited over time – in\nwhich case I’ll indicate that here.\n\n[id=\"copyright\"]\nCopyright and License\n---------------------\n\nOriginally published here: https://codeblog.jonskeet.uk/2010/08/29/writing-the-perfect-question/ ,\nwritten and Copyright by https://codeblog.jonskeet.uk/[Jon Skeet], 2010\nunder https://creativecommons.org/licenses/by/4.0/[CC-BY 4.0].\n\n[id=\"see-also\"]\nSee Also (added by GitHub contributors)\n---------------------------------------\n\n* https://github.com/shlomif/how-to-share-code-online[How to share code online]\n* https://github.com/shlomif/Freenode-programming-channel-FAQ[The Freenode ##programming FAQ]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshlomif%2Fwriting-the-perfect-question","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshlomif%2Fwriting-the-perfect-question","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshlomif%2Fwriting-the-perfect-question/lists"}