| Version 48 (modified by , 43 hours ago) ( diff ) |
|---|
Table of Contents
---
👉️ to get help, go to the Using Django category of the Django Forum.
---
---
---
---
Using the mailing list
There is also the older django-users@… mailing list.
However many users are unable to get full mileage from these venues as they are inexperienced in formulating their questions and in interacting with the list members. This page seeks to address this problem. Many members of the list, including core developers, take a lot of time and trouble to patiently answer questions asked, and we users should take as much trouble to ask properly formulated questions. Try to follow the steps outlined below to make for a more pleasant and rewarding experience on the list.
5-for-1
Like any project, if you show willingness to help and contribute then others are more likely to help you in the future.
Although it is not officially advertised, the majority of the core developers will participate in the 5-for-1 scheme. In a nutshell, if you spend time doing triage on 5 other tickets, you can request a core developer to look at any ticket of your choice.
The following guidelines apply;
- For every 1 hour you put in, you will get back roughly 3-5 minutes.
- The core developer won't necessarily offer a fix, but will give the ticket their full attention and generally give a more detailed response
- Typically speaking, a minimum of 30 minutes is a good guideline on how much time to spend in triage.
- If you spend 60+ minutes in triage on a single ticket, you can do a 1-for-1 request, but make sure you explain this in your mailing list request (as shown below)
Send your request to the list in a clear and concise manner, outlining what triage you did, what action was taken on each, and what ticket you would like in return, for example;
Subject: 5-for-1 request I have spent approx 1 hour doing triage on the following tickets; * https://code.djangoproject.com/ticket/xxxx - requested further info * https://code.djangoproject.com/ticket/xxxx - added comments, needs review from core dev * etc etc In return, could a core developer please look at the following ticket; https://code.djangoproject.com/ticket/xxx
Classify your question
There are different types of questions, each type requires a different level of detail. The most common type is about problem solving, and most of this page is devoted to this. Other types are:
Does Django have a particular feature?
Wrong way:
Does Django have scaffolding like rails?
Here you assume that everyone knows what rails is and what scaffolding is. Or you expect users to waste their time investigating. Do not do this. Explain what this feature is and what it does. Right way:
Foo framework has a feature that automatically generates html given certain keywords like 'abc' generates an 'xyz' widget, does Django have this feature?
How does Python work?
Asking question about Python related subjects is fine as long as;
- You follow the same guidelines as the rest of this document
- The question itself is somehow vaguely related to your Django project
- You understand that learning Django will involve learning Python as well.
For those who would like to read some tutorials on the basics of Python, you could try: http://wiki.python.org/moin/BeginnersGuide/Programmers
You can also try: http://learnpythonthehardway.org/
Is Django suitable for the app I want to build?
Questions on best practices
Try to find the answers yourself
- Most of the time, Google holds the answer to your question.
- Don't expect a 'one-shot / copy-and-paste' answer, there may be some work involved.
- Don't give up on the first page, it's not unusual to go as far as 400-600 results (depending on how relevant each hit is)
- Make full use of exception tracebacks, and don't be afraid to dive deep into the Django core code (this is a great way to learn + find hints about what caused your problem)
- Look through the django-users mailing list archive ( https://groups.google.com/group/django-users/topics?hl=en )
Google: Be imaginative with your keywords
If you are looking for information relating to say "Sphinx", just typing that in alone usually won't help.
Here are some common search alternatives you could try;
- Looking for a method/class called 'ReportBug'
ReportBug python "def ReportBug" "class ReportBug"
- Looking for items relating to Django models
"Django (model|models)" "from django" "import models" "howto" django models "problem with" django models
- Look for other peoples mailing list entries about MySQLdb
"django-users" "(problem|exception)" "MySQLdb"
- Be smart when it comes to looking for information about exceptions:
For example: OperationalError: (2002, "Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)")
Would become: django "OperationalError" "2002" "connect to local MySQL server through" "OperationalError" "connect to local MySQL server through" django "problem" "2002" "database"
More on where and how to search
The documentation is the best place to search. The only problem is that the search bar in the docs does not work well on multiple keywords. A search for date range will not give you the desired result. For this use the 'site' option in search engines like duckduckgo - http://duckduckgo.com/?q=site%3Adocs.djangoproject.com+date+range
The other place to search is the mailing list. If you must search blogs or forums, make sure that you check the date of the post and the Django version before complaining that it doesn't work.
Note that the documentation is excellent, but not perfect. It is mostly written by developers, and they often leave out things that are glaringly obvious to them, but not so obvious to the end user. At the same time they are very receptive when this is pointed out by us. Don't complain about the documentation; rather file a document bug if you come across such problems.
Prepare the question
Do's:
- Put a meaningful subject line - 'newbie needs help' *may* bring you a donation, but is otherwise useless. Use the keywords you used in your search.
- Indicate what your end goal is (or is not)
- Include tracebacks (where applicable; especially if there is an error). Make sure you *paste* the *full* traceback. Do not worry about using up space - you are not paying for it.
- Include a tested example of the code you are using.
- Indicate what attempts you have made to resolve the problem/issue yourself
- Ask yourself, what extra information might you need to resolve similar problems?
- Finally: proofread your question multiple times, rewriting for clarity and brevity as needed. You will greatly increase the chances of both getting help and figuring out your stumbling block this way.
Don't's:
- Post a user question to the developers' mailing list.
- Start a new discussion on an existing thread. Start a new thread for a new topic.
- Expect an instant or one-shot answer. The mailing list is not your personal tutor.
- Be vague e.g. "please help build a website". No one has time to write a vague answer.
- Keep repeating the same question. If anyone has an answer, you will get it sooner or later. If you post on a Friday or a weekend wait till people have a chance to get over their Monday hangover before expecting a reply.
- Obfuscate your code or invent code snippets - if you are reading this, your code is not rocket science and no one is going to steal it. Probably no one will take it even if you pay them.
- Use the phrase 'it doesn't work'. The most common question on IRC is: 'What does doesn't work mean?'
- Attempt to 'bump' your question by reposting it a second time. The mailing list is not a phpBB bulletin board.
Language
For many of us, English is not our native language. Try to follow English syntax, but do not waste everyone's time by apologizing. People will realise your difficulty and will ask for clarification if needed. However, please avoid using 'sms-speak' and refrain from being overly casual.
wrong:
i wan 2 make cms pls cn u hlp asap
Formatting your mail and your replies
Realise that not all users use gmail, and include sufficient context to make sure that the user does not have to waste his time searching the archives to find out what you are talking about. This means quoting enough of the mail you are replying to make your reply understandable and replying under the quoted matter. Example:
Question
The following code does not work. (code here) (error here)
two answers
> The following code does not work. > > (code here) > (error here) you have left out a comma in line 7
> The following code does not work. > > (code here) > (error here) correct the typo in line 3
The wrong way to reply
I tried, but it is still giving the same error.
who are you replying to?
the right way
> > The following code does not work. > > > > (code here) > > (error here) > > you have left out a comma in line 7 I tried, but it is still giving the same error.
Follow up
- Always make an effort to say thank you.
- If you feel someone did not understand your request (or gives an unrelated answer), then it's important you express this to them, and clarify further.
Report resolution
- Always make an effort to make your findings public. This may be in the form of a Django core ticket, djangosnippets.org, blog post, YouTube video etc. (Although sometimes, if the mailing list subject is descriptive enough, it may suffice to just have it in archive - which happens automatically.)
Real examples of how to ask questions properly
Real examples of how not to ask questions
Question is vague, with no thought behind it.
Question is vague, a simple Google would have yielded the answers OP needed.
OP did not include any code about how to re-produce the bug, and did not test on latest clean code for Django.
OP was extremely vague. See "Tom Evans" response for full reasoning on why OPs post is considered bad.
OP posted a question which was not related to Django/Python (or at the very least, had a very loose relation).
OP posted a question which Google answered very easily. Shows lack of intuition/laziness. Question also wasn't appropriate for this list.
Start answering questions
- Give something back to the community by answering questions you feel confident in.
How to answer questions on the list
- We were all newbies once. If you feel a question is too trivial to answer, do not flame - ignore the post.
- Ideally everyone who uses django should know the basics of Python, HTML, CSS, SQL and the HTTP protocol, but we do not live in an ideal world. If a post shows lack of such knowledge, gently point the poster to resources that would help.
- 90% of errors are explained in the last line of the traceback - this is not intuitive. The rest of the traceback needs an experienced hand to interpret. Educate users on the last line.
- If you feel the user hasn't made enough effort to find the answer themselves, explain to them why, and give them some guidance on how they can do this (point them to this page).
Real examples of how NOT to answer questions
- http://groups.google.com/group/django-users/browse_thread/thread/18ec8b88e52974ee/5f8d757781fa2fe4?hl=en#5f8d757781fa2fe4
- http://groups.google.com/group/django-users/browse_thread/thread/c20226440220c35c?hl=en
Other Issues
Inspecting Python objects
Here is a great mailing list thread which explains some good ways on how to inspect Python objects: http://groups.google.com/group/django-users/browse_thread/thread/69631b8fe7eb4412/ddf4bdb4b18e2997?hl=en&lnk=gst&q=Inspecting+objects#ddf4bdb4b18e2997
Migrating from other frameworks/tools
People migrating from other frameworks/tools face particular issues, mainly regarding basic concepts. We try to address some of these issues here.
Zope/Plone
- The fundamental difference here is that Zope is a *server* and completely self contained. It is a webserver cum database server cum templating engine. On the other hand Django is a loosely coupled set of components, and one has to set up the webserver and database outside the framework on one's own - and there is a plethora of choices for these.
- The Zope templating language is practically a programming language on it's own and it is common practice to embed script python code within templates. Django, on the other hand strictly limits the amount of logic one can put in templates, and it is impossible to embed python code in templates.
- Zope has clearly defined methods for adding extensions and products. Django does not.
- It is possible for an end user to produce an enormous amount of functionality in Plone without knowing anything about python in particular and programming in general, or css or html as all these are provided readymade. With Django you have to roll your own css, html etc and will not get very far without learning python and programming.