Grammar in the tutorial

[tmorgan]

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.

[durdinator]

I'm not sure where you've picked up this idea that '"will" should only be used with a specific time qualifier'. This usage may be preferred by some editors, but to call it an error--implying ungrammatical--is clearly nonsense, as any English speakers 3 years old or more could tell you. Nor is your advice itself consistent: you give "When the clock strikes twelve, the bell will ring" as an example you call 'correct', but you reject 'When somebody requests a page from your Web site — say, “/polls/23/”, Django will load this Python module' which is an identical construction.

I will clarify that I'm not complaining about your suggested changes being ungrammatical; they are clearly also grammatical. But I'm not convinced that anything needs changing in the tutorial. The examples you've highlighted--as you yourself pointed out--can be understood by anyone. The use of "will" here doesn't make the examples ambiguous, awkward, nor even particularly verbose, so nothing needs to be changed.

So I'm going to close this as invalid. If you find any actual errors, amibiguities, clumsy wording, needlessly verbose text, or other such issues that hinder the clarity of the tutorial, please raise a ticket with a patch or a suggested correction. But pet style hates don't belong.

[tmorgan]

Replying to durdinator:

I'm not sure where you've picked up this idea that '"will" should only be used with a specific time qualifier'. This usage may be preferred by some editors, but to call it an error--implying ungrammatical--is clearly nonsense, as any English speakers 3 years old or more could tell you. Nor is your advice itself consistent: you give "When the clock strikes twelve, the bell will ring" as an example you call 'correct', but you reject 'When somebody requests a page from your Web site — say, “/polls/23/”, Django will load this Python module' which is an identical construction.

I will clarify that I'm not complaining about your suggested changes being ungrammatical; they are clearly also grammatical. But I'm not convinced that anything needs changing in the tutorial. The examples you've highlighted--as you yourself pointed out--can be understood by anyone. The use of "will" here doesn't make the examples ambiguous, awkward, nor even particularly verbose, so nothing needs to be changed.

So I'm going to close this as invalid. If you find any actual errors, amibiguities, clumsy wording, needlessly verbose text, or other such issues that hinder the clarity of the tutorial, please raise a ticket with a patch or a suggested correction. But pet style hates don't belong.

Not a lot of confidence in your bug checkers if they close legitimate tickets without even reading them. It's obvious you didn't read my ticket from your reply.

Like I said, go look for the word "will" in any professionally edited instructional text and tell me what your results are.

I'll be back later with actual academic citation on why I am correct. This isn't "pet style hate," this is an important lesson I learned from my editor when I wrote things like this tutorial professionally.

[James Bennett]

As far as I can tell, these changes will not noticeably improve the tutorial.

[Karen Tracey]

Replying to tmorgan:

Not a lot of confidence in your bug checkers if they close legitimate tickets without even reading them. It's obvious you didn't read my ticket from your reply.

Like I said, go look for the word "will" in any professionally edited instructional text and tell me what your results are.

I'll be back later with actual academic citation on why I am correct. This isn't "pet style hate," this is an important lesson I learned from my editor when I wrote things like this tutorial professionally.

Oh, come now. Clearly durdinator read your ticket, he (I'm assuming durdinator is a he, if I've got that wrong apologies to durdinator) cited specific bits in his response.

I've never heard of this supposed rule either, but them I'm not a professional editor. However I do have a number of O'Reilly (since you specifically mention this publisher as one who gets this right) books on my bookshelf so I picked one at random and paged through it to see if I could substantiate your claim that 'will' needs a specific time qualifier. In "Learning the vi Editor" I found, after about 30 seconds of looking, on p. 20:

Give the change word command.  The end of the text to be changed will be marked with a $ (dollar sign).

on p. 53:

In addition, if you type the command: 

$ ex -r

or 

$ vi -r

you will get a list of any files that the system has saved.

So I do not find support for your assertion that 'will' must be used only with a specific time qualifier in my 30-second scan of a random O'Reilly instructional book. Really, I think your editor has led you astray into believing a style preference she has adopted is some sort of grammar rule: it's not.

[tmorgan]

Whatever, enjoy your extremely amateur looking documentation. I may not be exactly correct on how "will" is used, but I know you are using it far more often that is necessary. I was just trying to help.