Flutter still lacks useful examples

[Kimi Arthur]

Dear Flutter devs,

Flutter is awesome, but the doc/examples are still lacking.

Here are some examples that should be helpful. They can show usages and best practices for the whole community:

• A multi page app that uses sidebar to navigate (i.e. different scenarios) and depth to navigate (i.e. steps in one scenario).
• Third party signin/Google account signin flow.
• Apps with a service layer
• Code layout (folders, naming etc.)

Actually there is an example for navigation mentioned here. But it has no images to illustrate and it's put into the Sample Catalog page.

And to be honest, the documentation pages for classes are not that helpful since they don't have real, useful examples with images. For example the docs for Drawer, UserAccountDrawerHeader have no image. And even dialog, date picker don't have images. Even if you use the images shown from widget catalog, it is helpful (but not enough maybe).

Even if you read the doc, you still need to "guess" how to use them and more importantly how they look like.

And why that is important (not just put an image in the widget catalog) is that people may just search and find the widget class, and they will find no image for that.

And the same for Stack. It talks about "top"/"bottom", "position", "size" everywhere but doesn't use image examples to illustrate (there is a difference in the top / bottom thing in the two paragraphs in the doc).

Without an image, it's not super clear at first glance what it actually does. Especially the name doesn't tell whether it's about UI or about the navigation logic.

Some examples from Qt for reference: GridView, QMessageBox and even for StackView, a logical widget.

Flutter is awesome, really hope it gets loved by everyone.

Thanks,

Kimi

[Michael Tawiah Sowah]

I definitely agree with you Kimi Arthur, been struggling to understand this Stack thing and how it plays in the whole layout thing for a couple of hours now...I really hope they are able to do something about what you are saying.

and yes I love flutter and its Awesome.

[LarkAscending]

Good timing, as the Flutter team is currently working on more doc for navigation! We welcome threads like this one, to make sure we communicate what users need to know.

A follow-on question: Kimi, when you say

• A multi page app that uses sidebar to navigate (i.e. different scenarios) and depth to navigate (i.e. steps in one scenario).

by "different scenarios" do you mean, you want several pattern options to choose from for building a sidebar-navigating app? This app design usually implies a shallow navigation hierarchy. 

And by "depth to navigate (i.e. steps in one scenario)", you mean a more nested approach?

For the request to add a navigation example to the Sample Catalog, I'll create an issue.

Elaine Astrue

Technical Writer, Flutter

[Kimi Arthur]

Hi Lark,

Thanks for the reply!

I mean in navigation sense (i.e. shallow and deep hierarchy). Sidebar entries can be thought of as roots of navigation trees and steps can be thought of as branches/leaves in each tree.

So my intention is to have an example that demonstrate how the two ways of navigating (shallow ones with sidebar, and deep ones) work. Key things I'm interested in: how to push/replace (and pop when back) widget when navigating (tap on sidebar or tap on item in page). And again, it would awesome if there are diagrams about how the widgets (also states if applicable) stack in different situations.

Thanks! Keep the good work up!

[Michael Tawiah Sowah]

Kimi, I feel I have to vote up this again considering the experience am going through, I have looking for something on custom route/page transitions and its been over a day now and still nothing, practically slowed my development process, cos theres nothing in the docs clearly explaining with examples of it, and gitter am told try Stackflow where I still find nothing and then I even post it here and still nothing...kind of frustrating because with such an awesome product and this 'stress'... maybe I guess when I tell them the importance of my project then they will work closely like they did with Hamilton..lol...I mean the flutter team have been give really good support so far but something like transition(slide, explode etc) type for route/page sholudn't take me this long and still nothing and no response from any of the various platforms.

So Lark, while you are at it, you could also chip in how to change the route transitions to say slide, explode etc with examples in doc. 

On Sunday, September 3, 2017 at 3:39:28 PM UTC, Kimi Arthur wrote:

[amar...@gmail.com]

It would also be nice to have a sample app which uses bottomnavigationbar and navigation, and maintained state eg. scroll position etc. on changing tabs.

[Ian Hickson]

In addition to what Elaine said earlier, I encourage you to also file bugs so that we can make sure to track the requests. The more detailed the questions the better. Thanks!

--
You received this message because you are subscribed to the Google Groups "Flutter Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to flutter-dev...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

--
Ian Hickson

😸

[timo...@googlemail.com]

Hey there,

just started with Flutter, not really gotten very far yet aside from installing IntelliJ and starting the example.

It is great that some of the widgets already have visualizing images in the widget catalogue. It would be even greater if these were also in the widget's class documentation page. Currently, it's quite hard to navigate through the widget documentation and click from one widget to the next and missing the widget catalogue image examples.

I'm quite excited to dig deeper in the following weeks after making a 180 degree turn, now starting with Flutter instead of React Native..

[Ian Hickson]

Yeah, we totally intend to add more images to the docs (see e.g. the Card or AppBar API docs for some we've already done).

--

You received this message because you are subscribed to the Google Groups "Flutter Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to flutter-dev...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

--
Ian Hickson

😸

[Tao Dong]

Adding images to widget class docs is something we'd very much appreciate contributions from our community. If anyone here feels you can accurately create an annotated diagram or screenshot for a widget, we'd welcome your pull request. Please see the style guide for more information: https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#provide-illustrations-diagrams-or-screenshots

[Purusothaman Ramanujam]

Simple usage examples and images for each widget type would be really helpful. I am finding it hard to learn how to layout widget for the UI that I have in mind.

For important widgets like Row, Column, Stack some detailed image based explanation will be valuable.

[Scott Stoll]

Elaine? Just a quick point that I've raised elsewhere a couple of times. Please read to the end to see why this becomes an issue.

When using control + click to go to a class and read it's comments, it's much too confusing to figure out where one ends and another begins. All people would need is a simple, single line that serves as both a separator and header, like this:

// *************** InheritedWidget *************************

This way, if we were reading the item above this then we'd know where to stop... and if we were looking for info on the InheritedWidget we'd know to start reading just below the above header.

You might be thinking: "But using Control + Click takes you right to the class and it's comments, what's the problem?"

Well, Control +Click takes us to the top of the class, *not* to the top of that class' comments, which are located above the class. There could be a screen and a half worth of applicable comments above our cursor when that cursor is on the first line of the class itself, so we have to scroll up. *But how far are we supposed to scroll up?*

Well, common sense would tell me to scroll up until I see a header that says the name of the class I came to read about. But there isn't one. Worse, some comments are inside of the class and the way things are laid out, it's much too easy to keep reading right on through and not realize when you have reached the end of the comments for ItemA and started into ItemB.

Thanks for taking the time to read this and all the rest of the work that you're doing.

[Matej The Tree]

CTRL-J should give us everything we need, including examples, instead of going to the class itself. 

[Tao Dong]

Please 👍 this issue if you find usage examples and images important: https://github.com/flutter/flutter/issues/13637

These are useful signals for the team to decide what to prioritize. 

--