Discouraging Foreword in Documentation #181

mitsuhiko opened this Issue Feb 17, 2011 · 7 comments


4 participants

mitsuhiko commented Feb 17, 2011

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:


akavlie commented Feb 17, 2011

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.


ghost commented Feb 27, 2011

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.


ghost commented Feb 27, 2011

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.


mitsuhiko commented Jun 24, 2011

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


rduplain commented Jan 17, 2012

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.


rduplain commented Jul 15, 2012

@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 Jul 15, 2012

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment