Grammar in the tutorial
|Reported by:||tmorgan||Owned by:||nobody|
|Has patch:||no||Needs documentation:||no|
|Needs tests:||no||Patch needs improvement:||no|
Let me first say that overall the writing in the tutorial is excellent. I have been successfully teaching myself Django through its use and would recommend it to my 86 year old grandmother should she ever want to learn a new MVC system.
However, I have noticed an extremely prevalent error being made. The word "will" is often used incorrectly in instructional text, and the Django tutorial is particularly bad about this error. "will" should only be used with a specific time qualifier, like this: When the clock strikes twelve, the bell will ring.
Here's the first occurrence of the word "will" in http://www.djangoproject.com/documentation/tutorial01/
(I am keeping the entire paragraph to stress that this isn't simply taking sentences out of content in order to find flaw in them.)
"From the command line, cd into a directory where you’d like to store your code, then run the command django-admin.py startproject mysite. This will create a mysite directory in your current directory."
A rude editor would say, "When will the directory be created?" and, of course, we all know what you mean is that the directory is created when the startproject command is run. Anyone can understand that sentence, but technically it's wrong because the "will" does not have a specific time qualifier; it only has an implied one. The proper way to state this is:
"... This creates a mysite directory in your current directory."
It's that simple. Let's look at more of these examples I've randomly taken from various sections:
Tutorial Part 3
Wrong: When somebody requests a page from your Web site — say, “/polls/23/”, Django will load this Python module, because it’s pointed to by the ROOT_URLCONF setting.
Right: When somebody requests a page from your Web site — say, “/polls/23/”, Django loads this Python module, because it’s pointed to by the ROOT_URLCONF setting.
Note: You are qualifying the "will" by saying "When somebody requests a page ...", but it still is unnecessary because time isn't specifically involved.
Tutorial Part 4
Wrong: Using method="post" (as opposed to method="get") is very important, because the act of submitting this form will alter data server-side.
Right: Using method="post" (as opposed to method="get") is very important, because the act of submitting this form alters data server-side.
Wrong: request.POST['choice'] will raise KeyError if choice wasn’t provided in POST data. Right: request.POST['choice'] raises KeyError if choice wasn’t provided in POST data.
Wrong: HttpResponseRedirect takes a single argument: the URL to which the user will be redirected (see the following point for how we construct the URL in this case).
Right: HttpResponseRedirect takes a single argument: the URL to which the user is redirected (see the following point for how we construct the URL in this case).
And that is only scratching the surface on the "will" issue. There are many, many more examples.
Occasionally I point out how often "will" is used incorrectly to my nerd friends and they usually say they don't care. While I do not have some fancy citation from Some Old White Guy's Treatise On Using The Word Will to prove that I'm correct at some deeply academic level, I could probably come up with something if forced to. A very senior editor at a very big publishing company pointed this out to me when a bunch of text I wrote for her used "will" incorrectly just like you guys are. And if you aren't convinced at all, go open up any O'Reilly book and tell me how many times you see the word "will". I just flipped through 20 random pages of Learning Python (First Edition) and found it once: "In a moment, we'll ..." and you know that "will" is legit because it has "In a moment" qualifying it. I checked http://dev.mysql.com/doc/refman/5.0/en/regexp.html as well and the first "will" there is in a user comment. Professionally edited documentation should not have this problem.
So the whole document needs a deep proof reading/editing by an editor who really knows what they're doing. This 4th year English major can give it a shot if you don't have anyone better in mind.
Change History (5)
comment:1 follow-up: ↓ 2 Changed 8 years ago by durdinator
- Needs documentation unset
- Needs tests unset
- Patch needs improvement unset
- Resolution set to invalid
- Status changed from new to closed
comment:2 in reply to: ↑ 1 ; follow-up: ↓ 4 Changed 8 years ago by tmorgan
- Resolution invalid deleted
- Status changed from closed to reopened
comment:3 Changed 8 years ago by ubernostrum
- Resolution set to wontfix
- Status changed from reopened to closed