Bug in Flask docs
ed2050 opened this issue · 6 comments
Hi, flask seems very well done. The docs are well organized, with quick links to other sections.
However there's one bug I have encountered in the docs. Specifically this page has the following content:
Welcome to Flask’s documentation. Get started with Installation and then get an overview with the Quickstart.
Beautiful, prominent links to install and quick start.
There is also a more detailed Tutorial that shows how to create a small but complete application with Flask. Common patterns are described in the Patterns for Flask section. The rest of the docs describe each component of Flask in detail, with a full reference in the API section.
Tutorial, patterns, reference API. Fantastic!
Flask depends on the Werkzeug WSGI toolkit, the Jinja template engine, and the Click CLI toolkit. Be sure to check their documentation as well as Flask’s when looking for information.
A bit off the rails with minutia here, we can recover...
User’s Guide
Flask provides configuration and conventions, with sensible defaults, to get started.
Good to know.
This section of the documentation explains the different parts of the Flask framework and how they can be used, customized, and extended.
Great!
Beyond Flask itself, look for community-maintained extensions to add even more functionality.
Ok...
Here's where the bug is. In all that great intro information, there was not one single sentence telling me what in god's name Flask is. Is it a cocktail app? Is it for powder horn management? Is it a movement tracker for minutemen militia? Who knows? You wouldn't have any earthly idea.
Obviously I or anyone can google it. But we shouldn't have to. You did such a great job with the rest of the intro. You already have great explanatory text on the github readme:
Flask is a lightweight WSGI web application framework. It is designed to make getting started quick and easy, with the ability to scale up to complex applications.
Just put that at the top of the docs landing page and you're golden!
I would like work on editing this document and contribute to this project. I agree with Edward that we should have a few lines explaining what Flask does exactly.
Can this issue be assigned to me if there is a consensus about this? Thanks.
Ok @ed2050
@its-joseph-230606 please stop those noisy comments
@ed2050 Could you assign this issue to me? I have been blogging so I know how to put words together in a way that makes sense.
I don't seem to have permission for that. No way to assign things from this account as far as I can see...
Just send a PR. No need for assignment
PS: @ed2050, wouldn't it have taken less (or just as much) time to open a PR to fix this instead of writing this - very verbose - issue? ;)