Skip to content


Subversion checkout URL

You can clone with
Download ZIP


Discouraging Foreword in Documentation #181

mitsuhiko opened this Issue · 7 comments

4 participants


The documentation is currently very discouraging to many new users. We shouldn't have written the documentation that way because nobody else does and honesty is not expected I guess :)

Related feedback issues:


I found the docs in general to be so good, that I could get past this. However, some of the uncertainties that I think should be fleshed out:

1) What's a "larger application"? What's large to me is still tiny by enterprise standards. Is this "more than 5 views" large, or 300K+ lines large?

2) What sort of trouble can you get into with thread-local objects? That's not clear to me; examples would help a lot.

Regardless of how these are addressed, I think the sentiment is correct that the intro is not the best place to warn people about all potential pitfalls.


Actually, I quite appreciated the warning in the intro.

It was educational, since I did not think about it before.
It was considerate, since I was looking at flask for something specific, and that warning made me go a different route. I never like the "omg what a great framework ..... gotcha" stuff.
It was unique.

As I understand from rereading the answer I received when I asked that same question, and reading the docs problems will arise in event based or async cases, and in cases where the web server does not multiplex using processes.

Yet, people use flask with Twisted and tornado, which is confusing to me also.


Just in case my continuation based webrowsing style has messed up my reply.

Change nothing. The guy told the exact truth, and it's amazing how much flak he is getting for doing so.

@mitsuhiko Honesty is appreciated, thanks.


It's better by now but still not good enough. Pushed to 0.8


Looking better, but bumping to 0.9 to review further.


I know this hasn't really been discussed "lately", but since it has been bumped I wanted to write a quick comment.

I dibbled in some python and really only wanted to create small-ish web-applications and have a useable template-engine.
This was exactly what I was looking for and I think pretty much every part of it is excellent.
The documentation intro could be "cheerier" but honestly I don't think that is necessary. The documentation is very good and the Quickstart Guide made me start development right away because it really is as easy as the guide says.

The only thing I would complain about is the somewhat minimalistic wsgi documentation. People (like me) who aren't familiar with that might have an extensive trial and error phase on that one.

Thanks for keeping the doc free of any "we are so awesome, we can do everything" kind of tone, makes for an awesome read and the doc is very crisp and complete as far as my needs were so war.


@derdritte thanks for the feedback!

The foreword was re-written for 0.9, so we can close this. Regarding wsgi, imho, the Python community benefits from central wsgi documentation. Once you know how your framework conforms to wsgi, wsgi concerns are not specific to any web framework.

@rduplain rduplain closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.