Elaboration that might be helpful for new-comers

[kevinl@…]

The following are minor changes to present documentation that might help new-comers. (An experienced person would say what follows is obvious but for new-comers this might avoid confusion.)

In settings.py you might suggest to the student they name their first file something like:
'/home/[yourname]/projects/django-tute/mysite/mysitedb'. Warn them not to have any spaces before or after the string describing the path and file name or the syncdb command which will be used later will fail because it won't be able to find the file they have specified.

There is no guarantee that the student actually has installed a database engine. For example, the student may expect that, when installing django, they have, by default installed sqlite3. I suggest you tell the student to try:
sudo apt-get install sqlite3

If it is already installed then no harm done but it will ensure the student has a database engine to work with for the purposes of this tutorial. If the student is more advanced and intends to use PostgreSQL or FirebirdSQL then, once again, no harm done.

Next, suggest to the student, once they have installed sqlite3 to start the command-line utility for sqlite3 by typing "sqlite3" in the directory in which their mysite tutorial exercise is located. Then, once in the command line utility, to type ".schema" in order to view the tables that were automatically created in the file mysitedb that was populated by the syncdb command given earlier.

Tell the student that, to exit the command line utility for sqlite3, they type CtrlZ.

Hope this is helpful.
Kevin Loughrey
A Perfect PC Pty Ltd
Australia

[Ramiro Morales]

Replying to kevinl@…:

There is no guarantee that the student actually has installed a database engine. For example, the student may expect that, when installing django, they have, by default installed sqlite3. I suggest you tell the student to try:
sudo apt-get install sqlite3

If it is already installed then no harm done but it will ensure the student has a database engine to work with for the purposes of this tutorial. If the student is more advanced and intends to use PostgreSQL or FirebirdSQL then, once again, no harm done.

There is no such thing as a 'sqlite3 engine'. sqlite is a C shared library that (and here comes the good part) is already included with every sane Python installation of versions currently supported by Django (>= 2.6). So the tutorial is right about no asking users to install something that isn't actually needed.

[anonymous]

Ignoring whether sqlite is, or is not, an "engine", I am presently running LTS Ubuntu 12.04. The python I am running is:

print sys.version
2.7.3 (default, Aug 1 2012, 05:14:39)
[GCC 4.6.3]

For some reason, sqlite was not present. I had to install it. I was not aware that when installing Python > 2.6 sqlite would automagically be installed as well. Speaking of "magic happens"...one of the principles of Django is:

Explicit is better than implicit
This, a core Python principle, means Django shouldn’t do too much “magic.” Magic shouldn’t happen unless there’s a really good reason for it. Magic is worth using only if it creates a huge convenience unattainable in other ways, and it isn’t implemented in a way that confuses developers who are trying to learn how to use the feature.

The tutorial relies on the user having sqlite or some other software that supports the database functionality required by Django. Rather than assuming, it is there and isn't broken, I'm suggesting it would be a good idea to help a newbie by telling them in words of one syllable how to check all is OK. If you don't think that is a good idea then that's all there is to the matter. My feedback however is that it wouldn't hurt to help a newbie in every way possible because one day, some newbies become expert supporters and the world needs as many as it can get.

Kev L

[Aymeric Augustin]

This is a bug of Ubuntu (or at least a gotcha). Maybe we could document it in the platform-specific notes.

[kevinl@…]

Truly, this is quite a minor matter and it was raised only to try to be helpful. I am new to Django and I find it to be "a big elephant to swallow in one go" so I thought if we could remove as many "gotchas" as possible, it would increase the probability of new-comers persisting with it.

In all, I think the tutorial is of excellent quality. I have more comments that could improve its clarity but, really, I think as it stands, it is a very good effort and the authors should be very proud of their work.

As another suggestion in the spirit of reducing the amount a newcomer has to contend with, I suggest discussion be narrowed down in the first tutorial to only using SQLite but have a hyperlink to other databases where the more advanced reader would find a full explanation as to the syntax necessary to link Django to each of them. One database that is missing from the discussion entirely, and which I think should merit a mention in the more detailed discussion is FirebirdSQL.

My business partner, who is a degree-qualified computer scientist and very competent in both Windows and Linux administration, has succeeded in this. If you need assistance we could provide some words. We are presently experimenting in this area and, so far, enjoying some success.

[anonymous]

A correction to one of my earlier posts. I suggested the user should "CtrlZ" to exit out of SQLite. Reading the help documentation for SQLite, I see this is entirely wrong. It is ".quit". Doing a "CtrlZ" (I think?) stops SQLite and puts it into the background. Sorry for the mistake.

[Jacob]

Kevin, thanks for your comments; I've run into some of the things you describe teaching Django myself.

However, the number of things that can possibly go wrong during the tutorial is literally infinite; if we tried to document every single "gotcha" the tutorial would be more side-notes than actual content. The thing about sqlite is important, so I've opened #20077 about that, but otherwise I'm going to close this ticket out.