Documentation problems

[GoogleCodeExporter]

Hi, 
Thanks for the great piece of software. It's a tremendous tool, and I really 
appreciate your efforts 
both in building it, and supporting the user community. I just need to say 
something that I 
noticed in reading Graham's (ultimately helpful) responses to user questions. 

I was having trouble configuring my PYTHONPATH  in the django.wsgi file. I 
found half a dozen 
other people reporting having the same issue, and Graham's responses were found 
on all of 
them. In one, he expressed frustration with so many people having the same 
problem. Graham, 
the reason this is happening is that you do not write clearly. It is in fact 
wonderful that you take 
the time to do any of this documentation, and you are so willing to read random 
code snippets 
and help with the problem, but you are getting in your own way. The single 
biggest issue is that 
your constantly employ the passive voice. This is guaranteed in every case to 
be more confusing! 

Here is an example of it, and, I suspect, the cause of much of the confusion 
surrounding the 
correct settings for django with mod_wsgi : 
"The directory added to sys.path would be the directory containing the package 
for the Django 
site created by running: [...]"

Consider this. "Add the parent directory of your Django package to sys.path. 
Note: do _not_  add 
the Django package directory itself." I think this is much clearer.

"Aha," says you, "but I clarify in the next line! like so: 
In other words, it should be the directory you were in when 'django-admin.py' 
was run. It also 
equates to the parent directory of the directory which contains the 
'settings.py' created by 
'django-admin.py startproject'."

True enough, but this is still an incredibly convoluted way of saying, "The 
settings file you are 
trying to import is two levels below the directory you need to indicate"

Your word choice here is also somewhat problematic: "It also equates to"? 
Really? What is the 
intended antecedent of "It"? Why, it's "it" in the previous sentence. Now I 
have to skip back over a 
typographically distinct block to discern the antecedent of the antecedent-- 
ahh yes, the 
"directory". Uh oh, when I hop back to my working sentence, I see the word 
directory twice.  And 
"equates"? this is not the word you want. The word you want is "is".  Equate is 
to make equal, not 
to be equivalent to. In any case, like in programming, the simplest way of 
expressing the idea is 
probably the best.

I realize this has taken a turn  for the flippant, and I apologize if I seem to 
be picking on you. 
First, I am only able to crack wise about this because you have generously 
contributed your time 
and mental energy to creating something that I am using and admire a great 
deal. I am genuinely 
hoping to return the favor by contributing my time and energy into improving 
this project. Either 
directly (probably helping with docs, since I'd say it's safe to assume my 
coding chops are are not 
nearly serious enough yet) or indirectly by helping improve your ability to 
answer questions in 
the future. 
Since you post with great abandon, taking a quick look at the Elements of Style 
might be time 
well spent. A few simple steps will go a long way to reducing the total number 
of repeated 
questions-- I'm sure you code DRY, so why not write that way.  Avoid the 
passive voice and the 
subjunctive mood. Reread each sentence and strip it down to its necessary 
elements before 
hitting send. 

If you actually bothered to reach the end of this, Thanks! 
I really do appreciate the amazing work.

Ben

Original issue reported on code.google.com by bddbb...@gmail.com on 26 Nov 2009 at 11:15

[GoogleCodeExporter]

I know they need to be made better. Have another issue for that already:

http://code.google.com/p/modwsgi/issues/detail?id=63

The only thing I can hold in my defence is that the Django documentation on 
Django site covering mod_wsgi is 
actually even more confusing when it comes to setting up sys.path and whether 
or not parent or settings 
directory needs to be added. :-)

Anyway, I have had it in mind to do a much much more in depth and distinct step 
by step Django integration 
guide, ie. PDF booklet, for a while, but just don't have time.

Thanks for the feedback.

Original comment by Graham.Dumpleton@gmail.com on 26 Nov 2009 at 11:25

• Changed state: Accepted
• Added labels: Component-Docs, Type-Other
• Removed labels: Type-Defect

[GoogleCodeExporter]

Closing out documentation issues. Will pick up another time on github side when 
get enough momentum to work on documentation again.

Original comment by Graham.Dumpleton@gmail.com on 12 Nov 2014 at 10:22

• Changed state: WontFix