Asking Developer Questions

__NOTOC__
= How to get your question answered on xen-devel, mirageos-devel, win-pv-devel, etc. =
This document is about asking technical questions on the developer lists.
For advice on posting to the users' list, see User Questions and List Netiquette.
For advice on how to report problems, see Reporting Bugs.''
Most Xen Project developers actually enjoy answering well-considered,
well-expressed questions. But a question, even an interesting one,
that's not either of those things is a lot less fun. For example, an
email like this:
 From: AwesomeSauXe <hyns783nf@xxxx>
 To: xen-devel@lists.xenproject.org
 Subject: Help
 How function sh_unpin works???
 Thanks.
is going to take at least a few rounds of email before it's clear what's
going on. When someone answers this, it will be because they feel they
ought to; and by the time they've got all the extra information they
need to give a useful answer, they'll be a bit annoyed with the whole
business. And that's not going to lead to the most helpful possible
answer.
But if the question is clear and sensible and interesting, and if the
person asking is (or looks like they will be) a useful contributor to
the Xen Project community, then other developers will be happy to answer it,
suggest approaches, and sometimes even write patches. 
So how do you make _your_ question one that people _want_ to answer?
== Think about exactly what your question is. ==
First, try to get a precise idea of what you want to know. If you don't
know what the question is, there's no chance that the person trying to
answer it will know. If you ask a vague question, you'll get (at best)
a vague answer and need to follow up with the thing you actually wanted
to know. I often find that the discipline of deciding exactly what the
question is makes me realise what the answer is without even having to
ask.
Now that you know what your question is please consider whether a
developer list
is really the correct forum for it. Perhaps your question would be better
suited for the xen-users or another user list? 
In particular if your question is regarding
the installation or configuration of a Xen system then xen-users should be
the preferred list in the first instance.
== Use your tools. ==
Some questions can be answered without specialist knowledge. Always try
a search engine first; that might pick the answer out of a wiki or the
list archive. You can also use xen markmail.
Use developer tools like ctags or cscope or an IDE (or
grep) to find your way around the code. If you're working directly with
hardware registers or comms protocols, get a copy of the reference docs
and read it. Asking a question on developer list that could be answered
easily with a search tool may get you an answer, but it also makes you
look like a Bad Engineer, which makes it less likely that someone will
read and answer your next question.
Conversely, even if your search doesn't answer the question, it will
help you understand the question better.
== Pick the right list. ==
If you do not know which developer list is for you, either check the
developer list directory or
the team pages. 
 
== Set the scene. ==
If this is your first time on a Xen Project developer list, introduce yourself. It's usual
to give your name and affiliation, but not essential. Don't tell your
life story, but say hi, and say how you work with Xen. Are you a
sysadmin, or a kernel hacker, or a researcher (or all of the above)?
That lets people know what kind of answer is appropriate. Also it makes
them see you as a person, not some random string of characters @gmail.
Next, what's your overall aim? If you're debugging a hosting facility,
say so. If you're working on some cool new feature, _definitely_ say so:
that makes it clear that helping you brings a direct benefit to the
Xen Project. Also, it may be that there's some much better way of doing
what you want that avoids the whole problem; and that's much more useful
than an answer to the immediate question.
== Express your question as clearly as you can. ==
Having given enough background to explain why you're asking this
question, ask the question. Do it as plainly and clearly as you can.
Give enough detail that someone who's not familiar with your work can
figure out what you're doing (but don't just post your entire code and
say "where is the bug?").
As it happens, developer list discussions happen in English, so if you don't
speak English well, consider getting someone to help you. Also,
remember that the person reading your question can't see into your head:
you need to try and formulate the question in terms that _they_ will
understand. Try not to use the jargon of your own project or OS. 
Try to be civil too. You may well be furious and frustrated after a
week fighting some horrible piece of Xen Project code, but remember your aim is
to get the authors of that code to help you, so calling them names isn't
a good idea. Find another outlet for your rage, and ask nicely.
== Observe list etiquette. ==
Xen Project developer lists, 
like many open-source mailing lists, keeps to a set of
conventions established in the '80s and '90s. They may seem a bit
archaic these days, but breaking them is another way to make yourself
look like a Bad Engineer. There are a number of guides on the web, 
but some particular points that seem to show up on our developer lists are:
* Please post in plain text (i.e. not HTML), word-wrapped to somewehere around 72 characters.
* Please don't top-post. Meaning answer below the asked question, not on the first line of the email.
* Please trim the quoted material in your reply to only include the bits you are responding to.
** This is particularly important if reply to the digest mail. Be sure to trim down to at most the mail you are responding to as well as adjusting the Subject line to reflect that mail rather than the digest title.
* Please start a new thread for a new question (don't just reply to a random email from the list).
* Please don't email questions directly to xen developers. Keep the conversation on the list where other people (and search engines) can see it. This also applies to private instant messaging.
* Please do not cross post to multiple xen-* mailing lists. Please pick the one which most suits your questions. An exception can be made when moving a thread between lists (e.g. from xen-users to xen-devel).
Category:Developers
Category:Development Process
Category:Xen