'Integration With Django' wiki page suggestions

12 views
Skip to first unread message

Dave Everitt

unread,
Jul 17, 2010, 5:44:58 AM7/17/10
to modwsgi
I found the Google code mod_wsgi wiki pages very useful and clear and
got mod_wsgi up and running quickly.

However, the 'Integration with Django' page (http://code.google.com/p/
modwsgi/wiki/IntegrationWithDjango) isn't as clear as the 'Quick
Configuration Guide' and 'Configuration Guidelines'. Perhaps it could
be made clearer by adding subheads, and appear more up-to-date as
follows:

1. Collect information and issues already raised in Django tickets for
any *pre-1.0* versions of Django, under a subhead 'Older versions of
Django', so users of recent (backward compatible) versions don't have
to see irrelevant info (e.g. 'Be careful using the BuildBot
djangorecipe version 0.17...', 'Django's WSGI adapter prior to alpha
versions of version 1.0...', 'HTTPS detection done by Django was wrong
for WSGI...' etc.).

2. Since (as I understand it) from Django 1.0, successive versions are
backward-compatible and the majority(?) of developers are using at
least that version, make it clear at the top (instead of 'Requires
Django 0.90') that these instructions apply mainly to Django >= 1.0,
then collect version-specific issues under the 'Older versions of
Django' subhead.

3. Separate Windows-specific information under its own subhead.

4. Perhaps similar for Apache - mention up front that the instructions
apply mainly to Apache 2.*, and - although they will also work with
1.* - the main difference is that WSGIDaemonProcess will not run.

5. It would - in the Python spirit - be good to have 'one obvious way'
of setting things up e.g. - daemon mode, an ideal directory structure
within a *nix user directory, a typical VirtualHost block, etc., then
cover other options afterwards.

If it helps, I'm a good sub-editor and have a passion for making
instructions as simple as possible, although I'm sure others in the
community are more knowledgeable.

Graham Dumpleton

unread,
Jul 17, 2010, 6:44:14 AM7/17/10
to mod...@googlegroups.com
See http://code.google.com/p/modwsgi/issues/detail?id=63

It has been listed as a task for a long time.

Realize that mod_wsgi is a one man project. I have very liitle time to
work on mod_wsgi as it is. It isn't like I get people donating me huge
amounts of money such that I don't still have to work for a living.
:-)

Also why should I be making high quality documentation for someone
else's project. Frankly that is a beef I have had with various
projects, they assume that I will do things for them rather them
developing their own decent documentation for the users of their
product.

That all said, I have had plans for quite a long time to develop
documentation of great detail specifically focused around Django, but
ultimately it comes down to what is in it for me. There ultimately is
a limit of what I am prepared to do for free.

BTW you should ensure you watch my PyCon talk where I do use Django as
an example.

http://blog.dscpl.com.au/2010/06/sydney-pycon-modwsgi-talk-slides.html

Can you also perhaps add your suggestions as a comment against that
issue in the issue tracker.

Graham

> --
> You received this message because you are subscribed to the Google Groups "modwsgi" group.
> To post to this group, send email to mod...@googlegroups.com.
> To unsubscribe from this group, send email to modwsgi+u...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/modwsgi?hl=en.
>
>

Dave Everitt

unread,
Jul 17, 2010, 8:45:59 AM7/17/10
to modwsgi
I've added a condensed version of my points to the issue tracker.

I do realize this is a one-man project, and that this one man also has
to earn money, and am therefore grateful and will probably donate
something from my own (currently meagre) income. I agree about the
"documentation for someone else's project" issue, but often find other
project documentation over-complex, so (partly for my own sanity but
also to help the community) I sometimes re-write it in the simplest
possible terms (e.g. South and Django: http://gist.github.com/453421 )
and since Django has the largest(?) user base of all the possible
applications I thought the Django integration page on the mod_wsgi
wiki would be a good place to start as a template for the other
integration guides.

The bit about me being 'a good sub-editor' with 'a passion for making
instructions as simple as possible' means I'd be happy to start
editing a draft of that particular page for approval. If that helps at
all.

And thanks for the PyCon talk link :-)

Graham Dumpleton

unread,
Jul 17, 2010, 7:01:39 PM7/17/10
to mod...@googlegroups.com
On Saturday, July 17, 2010, Dave Everitt <dever...@gmail.com> wrote:
> I've added a condensed version of my points to the issue tracker.
>
> I do realize this is a one-man project, and that this one man also has
> to earn money, and am therefore grateful and will probably donate
> something from my own (currently meagre) income. I agree about the
> "documentation for someone else's project" issue, but often find other
> project documentation over-complex,

Yes understandabilty is an issue. My bigger complaint about third
party documentation provided with other packages is incompleteness.
Not only is important stuff missing, the whole document is written by
developers who generally have a better base understanding of things.
Thus often not real good for absolute newbies.

I can't claim my documentation is perfect either as information is all
other place and I don't have the absolute newbie step by step
tutorial. Either way, I do get annoyed though when people will not
even bother to try and read the documentation in the first place and
who instead come to you expecting to be to spoon fed on every minor
point along the way. These people seem to be totally oblivious to the
fact that they are wasting your time. They treat you like a help desk
who is only there to serve them.

Being a bit of a perfectionist, I really do want to do some better
documentation. Because I expect the tools to probably work well for
me, I was looking at using Pages on a Mac/iPad and pushing drafts up
to the iWork site with people being invited to participate to review
and comment on them. It would thus effectively be a evolving document
over an extended period with possible periodic drops to a public site.

The issue with putting all that effort in is how you get some due
compensation. I am not too keen on the idea of publishing a dead tree
version. Plus from what I have seen to date, people in the Python
community are tight arses when it comes to money. When web2py author
put his documentation on scribd and charged people for it, there were
so many complaints.

I should highlight that I am not expecting to be rolling in money from
this as unless there is some angel out there with lots of money to
throw around, will never get back what I have put into this. Right now
the number of donations amount to a lot less that 1% of downloads, so
few that one would need a lot of zeros in that percentage after the
decimal point. It is more about getting at least some sense of feeling
that people value what one does. Any donations nearly always end up
buying stuff for my two and half year old daughter such as clothes,
toys, books or as is developing, games to feed her growing iPhone game
addiction.

I have been thinking of late about making the request for donations a
bit more prominent and also make suggestions for how much.
Specficially looking at suggesting that people who use mod_wsgi for
personal sites contribute what it costs them for one month of web
hosting for their site. If a commercial organization using it for
their own site, then two times that value. If a managed hosting
service that is making money off other people, then three times what
they charge their customers for one month of their hosting services.
When you look at this that isn't a great deal of money and for
personal users is usually going to be less that $20. You still will
not get many people feeling they get enough out of the software to
make a contribution, but hopefully it may encourage something more
than the small number of contributions that get now. That way I feel
it is a bit more valued and I will continue to put in that extra
effort that I do when you compare what I do to other open source
projects.

> so (partly for my own sanity but
> also to help the community) I sometimes re-write it in the simplest
> possible terms (e.g. South and Django: http://gist.github.com/453421 )
> and since Django has the largest(?) user base of all the possible
> applications I thought the Django integration page on the mod_wsgi
> wiki would be a good place to start as a template for the other
> integration guides.
>
> The bit about me being 'a good sub-editor' with 'a passion for making
> instructions as simple as possible' means I'd be happy to start
> editing a draft of that particular page for approval. If that helps at
> all.

I'll definitely get back to you if I go down this path or some better
documentation as describe above.

Graham

> And thanks for the PyCon talk link :-)
>

Dave Everitt

unread,
Jul 18, 2010, 6:57:37 AM7/18/10
to modwsgi
Thanks for the reply. Before some final responses, I'd just like to
say that your documentation worked fine for me.

As for the Django docs on the subject I'm surprised - given "Deploying
Django with Apache and mod_wsgi is the recommended way to get Django
into production" - that mod_wsgi on the Django wiki is poorly-covered
(e.g. http://code.djangoproject.com/wiki/django_apache_and_mod_wsgi)
and barely mentioned in the current version of the Django book (so I
added a comment under the subhead 'An Alternative: mod_wsgi'
http://www.djangobook.com/en/2.0/chapter12/).

Instead of writing it all up yourself, ideally you should just be able
to point Django users (like you do for CherryPy) to
http://docs.djangoproject.com/en/dev/howto/deployment/modwsgi/ then
open tickets for any incomplete info on that page, to encourage the
Django community to improve the info. For those who want more, the
page already links to your docs (and says nice things about them). My
original suggestions were aimed at making what's on the mod_wsgi wiki
better than the Django doc page, but that might be the wrong way to go
about it, especially since it then becomes your responsibility, when
it should be shared with the Django community and developers.

> Yes understandabilty is an issue. My bigger complaint about third
> party documentation provided with other packages is incompleteness.
> Not only is important stuff missing, the whole document is written by
> developers who generally have a better base understanding of things.
> Thus often not real good for absolute newbies.

I think this kind of info is best presented in layers of increasing
depth:
* minimal newbie info (just get up and running) >
* more detail (practical options, typical scenarios/errors) >
* full documentation.

Developers inevitably take their own knowledge for granted (and
gradually forget what it was like starting out), so keeping the newbie
in sight (remembering they may be a newbie to this, but knowledgeable
in other areas) is a good reality check.

> I can't claim my documentation is perfect either as information is all
> other place and I don't have the absolute newbie step by step
> tutorial. Either way, I do get annoyed though when people will not
> even bother to try and read the documentation in the first place and
> who instead come to you expecting to be to spoon fed on every minor
> point along the way. These people seem to be totally oblivious to the
> fact that they are wasting your time. They treat you like a help desk
> who is only there to serve them.

It's the old RTFM thing - as Django gains ground I'm seeing an
increasing number of these kinds of posts on forums when, instead of
an answer, all people really need is to be referred to the relevant
'minimal newbie info', but not the full docs. I saw one recent Django
question that wanted to know what the word 'regex' meant, but we all
have to start somewhere. Way back then, I would have instantly
searched for anything I didn't understand (partly to not appear
stupid), but not all newbies are considerate, nor do they always
realise they're being a pest. It's easy to forget (or actually, be
constantly reminded) how steep the learning curve can be at times.

> Being a bit of a perfectionist, I really do want to do some better
> documentation. Because I expect the tools to probably work well for
> me, I was looking at using Pages on a Mac/iPad and pushing drafts up
> to the iWork site with people being invited to participate to review
> and comment on them. It would thus effectively be a evolving document
> over an extended period with possible periodic drops to a public site.

I think your docs are fine as they are. You can't be expected to write
all the framework-specific info as well, just to point out any
inconsistencies/problems/improvements.

> The issue with putting all that effort in is how you get some due
> compensation. I am not too keen on the idea of publishing a dead tree
> version. Plus from what I have seen to date, people in the Python
> community are tight arses when it comes to money. When web2py author
> put his documentation on scribd and charged people for it, there were
> so many complaints.

No need for a dead-tree version. Many of us (not just the Python
community) are tight arses simply because we're in the same boat i.e.
doing stuff because it scratches our own itch, or because we're
interested enough to make the effort. My clients have dried up and the
Uni where I teach is cutting back, but (looking on the slightly less
grey side) that gives me time - but no money - to expand my own
knowledge base, make new stuff, and (often) write up how to do it for
others.

> I should highlight that I am not expecting to be rolling in money...

As for that, obviously mod_wsgi isn't a money-spinner, but there's a
copy of Souders 'Even Faster Websites' on the way from your wishlist.

> > The bit about me being 'a good sub-editor' with 'a passion for making
> > instructions as simple as possible' means I'd be happy to start
> > editing a draft of that particular page for approval
>
> I'll definitely get back to you if I go down this path or some better
> documentation as describe above.

Please do. I'll probably have written up my own 'simple as possible'
guide by then, with links to your docs.

No need to reply

Dave
Reply all
Reply to author
Forward
0 new messages