618
edits
How To Ask Questions: Difference between revisions
add disclaimer
| [unchecked revision] | [unchecked revision] |
mNo edit summary |
(add disclaimer) |
||
| (29 intermediate revisions by 2 users not shown) | |||
Line 1:
{{OSDev.org disclaimer}}
These are a few hints for the first-timers and other newbies to maximize your chances of getting a useful answer to your question and have the community pleased to help you rather than annoyed by your complaints. It has been inspired by the [http://www.catb.org/~esr/faqs/smart-questions.html How To Ask Questions The Smart Way] document which you can easily retrieve with a web (Google) search. The guide here is only the subset of the 'official' document by Eric Raymond that applies to web fora (and this forum in particular).▼
▲These are a few hints for the first-timers and other newbies to maximize your chances of getting a useful answer to your question and have the community pleased to help you rather than annoyed by your complaints. It has been inspired by the [http://www.catb.org/~esr/faqs/smart-questions.html How To Ask Questions The Smart Way] document which you can easily retrieve with a web (Google) search. The guide here is only the subset of the
'''Note:''' ''While it should be obvious, it nonetheless comes up often enough that it needs to be said - Eric S. Raymond and Rick Moen should '''never''' be directly contacted for assistance with any software project which they are not personally involved in! The very fact that this occurs at all indicates that the readers of sites like this have not read and understood their recommendations. Since the authors have specifically asked that this warning be included with any link to their document, it needs to be emphasized at every possible opportunity.''
Line 14 ⟶ 16:
Bad grammar, spelling and/or punctuation makes your post '''much''' harder to understand. You will end up with people either ignoring your post or debugging your language instead of debugging your problem. Stay away from 1337 and SMS shortcuts, too. Basically, use proper English (whether that happens to be UK or US spelling is largely irrelevant).
As a side note, the OSDev.org forums do not currently have any subfora for languages other than English. This is deliberate. Splitting the forums up more means less people will read and be able to answer to each topic. Eric S. Raymond has also made the point that programming in general (and OS development in particular) is a topic with so many
== Programming Background ==
OS development is not a reasonable place to learn how to program in C, Assembly, or any other language, something that is pointed both in this wiki and in the forum rules. These warnings are there for a reason, and asking a question that indicates to us that either you didn't read and understand those rules, or chose to ignore them, is unlikely to garner much sympathy here.
It is true that the OS development fora have a reputation for being harsh towards newbies. There's a reason for this: OS development isn't a topic that a newly-minted programmer can reasonably approach. A lot of people jump into the field too early - before they have the background and experience to really understand what they are doing - and get burned by their lack of preparedness. Unfortunately, this leads to us seeing a lot of the same mistakes and problems again and again, ones which could be avoided if the poster had simply read those warnings and followed their advice.
This is not a field that you can learn through simple tutorials, especially if you're do nothing but copying and pasting the tutorial code and trying to make it work without understanding it. The tutorials that do exist - and for most subjects in this area, there aren't any, and their cannot reasonably ''be'' any - are meant as guidelines, not cookbooks. Cutting and pasting code out of several different existing sources and expecting them to magically fit together is simply an unworkable approach to OS development. You will need to learn a lot, and thoroughly understand what you are doing, before you can expect to approach this field in a meaningful manner.
== Research ==
Line 26 ⟶ 35:
You're less likely to get the response you were looking for by asking general questions like "how do I read from a FAT disk?", "how do I load program?", or "are there any memory management tutorials?" Asking such questions shows a lack of an essential programming skill; a programmer should able to solve problems by him/her self, and is a clear indication that one has not done their research. A better example could be rephrasing the question as "I am trying to do X. I have done Y, but I do not fully understand Z."
=== Regarding Outdated or Incomplete Wiki Articles ===
It is a sad truth of any large collaborative project such as a wiki that inevitably, some information becomes outdated without it being noticed. Just as inevitably, some subjects simply don't get the attention they need. If you notice something where you think this has happened, please try not to get angry; instead, politely bring it up on the message board, so someone - possibly yourself - can add to it and/or update it.
It may be that it was simply missed until now, or that no subject-matter expert had addressed it yet; it may also be that someone has hoisted a copy of the page to their own private pages in order to do a major overhaul, which isn't reflected in the official page yet. It could even be that there is contention over how to address the topic, which has delayed planned updates. Conversely, it may be that you missed something somewhere else (which can certainly happen, given the size and sprawl of the wiki), and forum-goers familiar with the topic can point you in the right direction. In either case, it would be better to be constructive and pro-active rather than flaming about it.
== Details ==
Line 37 ⟶ 51:
Try to find a minimum code subset sufficient to reproduce the problem. (That's also a good debug technique; you might locate the error yourself in the process.)
As always, one key component of any OS project should be an off-site source control repository; in addition to the advantages regarding code retention and backup, it allows responders to view the code in question without having to either wade through a large code post, or have to ask for the code to be posted over and over again. If you have such a repository (and you should), be certain to include a link to the location of the code section you are having trouble with. This will allow the forum-goers to see the latest version of the code, and refer to it directly. As already stated, you should limit code posts to exactly that part of the code that you are having problems with; if the problem proves to be elsewhere, the repo should permit that to be determined over time.
== Formatting ==
Line 42 ⟶ 58:
Split your post in paragraphs of a few sentences. Do not shout (e.g. WRITING IN CAPITALS) or use nifty but useless formatting (like glowing colored fonts, moving text, lines of smilies etc.). Use the 'preview' feature if possible.
== Describing Goals ==
When one is working a particular problem X, it is not uncommon to find a solution Y which looks to be a suitable, but which you don't know how to implement correctly, or have problems debugging. This may lead you to post a question on how to do Y correctly. This is fine, ''except'' that doing so without explaining the context (problem X) of why you want to solve problem Y may lead to answers which solve Y, but not in a way that solves X. Indeed, it may be that Y doesn't solve X at all, or that there is a significantly better solution to X which you aren't aware of. In this case, asking about Y is going to lead you down a blind alley. At best, it may leave those who could reply confused as to your goal, causing them not to reply at all even if they might actually know how to solve X.
This sort of false solution is known as the [https://en.wikipedia.org/wiki/XY_problem XY Problem] (or more humorously, a [https://weblogs.asp.net/alex_papadimoulis/408925 'Bottle or Old Shoe' Question]), which is one of the most frustrating communication problems one can have on a forum.
In order to avoid this, you should carefully consider whether you have explained enough about what you are trying to accomplish when asking for help. You don't need to give a detailed account of your project, but a thumbnail sketch of the immediate goal (and any solutions to it you have used in the past) can go a long way in setting up enough context for the respondents to knowledgeably answer your question.
== Identifying the Problem and Describing it to Others ==
Try to isolate your problem as far as you can before posting about it, and give as much information as you can in your post. Both too little information, and too much, make it harder to answer the questions, but in general too much is better than too little.
When asking for programming help in general, it is usually advisable to give a [http://www.sscce.org/ Short, Self Contained, Correct (Compilable), Example], isolated from the actual codebase. However, in OS Dev, this may not be possible, as bugs are often closely tied to the overall environment, and in any case isolating code for kernel or driver operations may not be possible. If you can give one - even if it requires some additional scaffolding - then do so, as it will go far in isolating the issue from extraneous details, but we won't fault you if you can't (though we might if you ''won't'', as it is rude not to at least try).
=== Posting Code Samples versus Linking to a Repository ===
In explaining a problem it is likely that you will need to provide either code samples of the problem section(s), or a link to your code repository, or both. In general, when posting code samples, you want to give enough code to illustrate the problem, and no more. Just how much that is can be difficult to judge, however. Also, extremely long code samples tend to be hard to read through in a post, so if you have more than (say) 50 lines of code in a snippet, it may be better to link to it instead. Even with a smaller snippet, including a link to your repo is appreciated, as it may allow us to get some additional context for the issue.
Note that posting code, or a repo link, and telling us 'this doesn't work' is not sufficient. It is extremely rude to simply give a large code sample or a link to a repo and expect us to answer your problem without at least telling us where in the codebase you think the problem lies. Doing so without explaining the failure mode (i.e., what is or isn't happening) is even more so. One would think this wouldn't need to be said, but apparently it does.
----
| |||