Improve foreword #438

merged 4 commits into from Mar 14, 2012


3 participants

garbados commented Mar 12, 2012

I've changed a few words, but there's plenty I'd like to change / restructure about this Foreword.

Who is this foreword intended for? Experienced Pythonistas who are new to Flask? Folks who are new to flask regardless of their Python experience? Right now, this is a good foreword for the first group: its examples cover advanced topics that newer users won't understand, and whose only effect will be to scare those users. I would recommend splitting the foreword into two parts: (1) For new users (2) For experienced coders. This first portion would cover, in broad strokes, Flask's philosophy: convention over configuration, what "micro" means, "simple tasks should be simple", etc. The second portion, which we may want to hide on another page, will cover the implementation details of Flask's design decisions that advanced users will want to know about, such as the use of thread-local objects.

If that's a structure the community feels good about, I'd be happy to draft it up.


garbados commented on 74a72e8 Mar 12, 2012

Oh jeez, I misspelled foreword, really? Dag.


rduplain commented Mar 12, 2012

@garbados Sounds good. Go for the two sections you describe.


garbados commented Mar 12, 2012

Sweet. In progress.


garbados commented Mar 13, 2012

Regarding "Web Development is Dangerous", what is the point of this section? What makes Flask different from any other framework such that we need to make special mention that putting stuff on the internet poses problems? The gist of the section, "So always keep security in mind when doing web development.", strikes me as unnecessarily scary to beginners and not worth mentioning to veterans.

If one were to rewrite the "Web Development is Dangerous" section to inform the user of how Flask handles security and possible gotcha's, then I would have found the section to have some meaning the given context. But the way it stand now I agree with garbados's sentiment.


rduplain commented Mar 14, 2012

I like the rewrite. I'm pulling and updating the text. Thanks for sprinting!

rduplain added a commit that referenced this pull request Mar 14, 2012

@rduplain rduplain merged commit d626787 into pallets:master Mar 14, 2012


garbados commented Mar 15, 2012

Yay! Thanks!

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