search

flutter / website

Flutter documentation web site
https://docs.flutter.dev
Other
2.81k stars 3.21k forks source link

Issue(s) with FriendlyChat Codelabs tutorial, suggested easy solution(s). #2083

Closed zoechi closed 4 years ago

zoechi commented 5 years ago

@ScottS2017 commented on Fri Dec 08 2017

(EDIT: There are a few other little things I'm seeing so I'll add them in comments. I've been trained to teach and have presented seminars to groups so don't worry... my feedback will always be constructive and I'll make it actionable if at all possible.)

Since I'm probably the newest person around here I might be able to give a point of view that the team doesn't see much. I'm teaching myself Flutter, starting from nothing, so I might run into situations the team doesn't normally see... like this gem:

Brand new person (me) starts doing the FriendlyChat app tutorial in Codelabs. I make the starting app. I'm curious, so I run it. All is good, and IntelliJ shows a notification that I can do hot reloads and that I should try it. Great! Now I go do the tutorial with my running starter app. On page 4, I create my new Material App and pass it to runApp(). The tutorial says to run it and look at the new, blank app. Okay, so I do a hot reload and it explodes:

I/flutter ( 2592): 'file:///home/scott/Coding/Flutter/myprojects/codelabs/codelabs_friendly_chat/lib/main.dart':
I/flutter ( 2592): malformed type: line 22: cannot resolve class 'MyHomePage' from 'MyApp'
I/flutter ( 2592): home : new MyHomePage(title : "Flutter Demo Home Page"),

The problem is that you can't run an app that has MyHomePage, get rid of MyHomePage and try to hot reload because hot reload is apparently trying to change the state of MyHomePage, which doesn't exist anymore. I only know this because last night I listened to the FLOSS podcast episode with Adam Barth and he described how hot reload changes the state of existing widgets. What if I didn't know this? And what if I didn't belong to Gitter or know how to get help?

The fix was, you guessed it, to stop the app and restart. Having just listened to Adam's interview, I realized this pretty quickly. However the vast majority of people doing this tutorial will be playing with hot reload and have no idea how it works.

So when (not if) this happens to them, one of their very first experiences with Flutter would not be good.

Solution: On page 3 there is a big note warning you to remove the widget_test.dart file. We need another warning on page 4 telling the user that they have to stop the app and restart after deleting the starting code and creating the main scaffold.

It's that easy. Just tell them: "Hey, you gotta stop completely and restart here or it won't work."

@ScottS2017 commented on Fri Dec 08 2017

Very minor issue on Page 4. Please remember that the novice does not think ahead very much when reading a tutorial. They expect, and need, the tutorial to walk them by the hand. That said, take a look at the paragraph:

Build the chat screen

To lay the groundwork for interactive components, you'll break the simple app into two different subclasses of widget: a root-level FriendlychatApp widget that never changes, and a child ChatScreen widget that can rebuild when messages are sent and internal state changes. For now, both these classes can extend StatelessWidget. Later, we'll adapt ChatScreen to manage state.

So new person, me, has heard a little about stateless widgets and widgets that can change state. Reading this, I see that the root level is stateless and the child isn't. But both will be started with stateless widgets but later we adapt the ChatScreen, which we just said is a stateless widget, to manage state.

Huh? We're going to adapt a stateless widget to be able to change state... but is it stateless or not?? New novice is now confused.

I had to read that 3x and think about it; and I can only assume that we're going to get rid of the stateless widget and use one that can change state. Maybe that's what we're going to do? I'm still not sure because I haven't gone past this point yet.

Actionable Solution(?): If this is the case, then a more clear way to communicate this to "Joe Noob" would be to change that last sentence to something like:

Later, we'll swap out the stateless widget and instead use one that can change state for our ChatScreen. That way we'll be able to change it's state as needed.

This has been the Noob Report. Tune in next time for "What's a Scaffold?"

Thanks! Scott

@sethladd commented on Fri Dec 08 2017

cc @LarkAscending

@ScottS2017 commented on Fri Dec 08 2017

Side note: I wonder if Google would hire me to give running feedback on the experience of a novice who is trying to learn Flutter from nothing, as part of QC... but with an actual novice who knows how to give actionable feedback.

Hey, a guy can dream, can't he? :D

@ScottS2017 commented on Fri Dec 08 2017

Last, very minor, point on page 4:

"Some widgets, like Scaffold and AppBar, are specific to Material Design apps. Other widgets, like Text, are generic and can be used in any app. Widgets from different libraries in the Flutter framework are compatible and can work together in a single app. "

When I read: "Some widgets, like Scaffold and AppBar, are specific to Material Design apps."... I think to myself: what is a Material Design app?

I really don't know. I'm not playing the part of a noob here, I am a real noob, and I really still don't know. I'm not asking you to answer the question here, I'm pointing out that:

Actionable Solution(?): Maybe something like:

"Some widgets, like Scaffold and AppBar, are specific to Material Design apps. A Material Design app is one that (basic description here). (Now resume with:) Other widgets, like Text, are generic ... "

Overall the tutorial is doing a great job of teaching me a lot of these things and I'm really enjoying it! Great work so far and I only hope that my observations help you to fine tune it even further.

@LarkAscending commented on Fri Dec 08 2017

@ScottS2017 Thanks for this feedback on what you found confusing!

You are right, the hot reload feature has changed slightly since the codelab was last updated. We're testing codelabs with it now... And more content on state is planned soon! The codelab is very looong and tries to keep moving, rather than going into details of the framework.

Big question: when these questions came up for you, did you try to resolve them via flutter.io and/or docs.flutter.io? The codelab assumes that noobs are doing that to answer questions about Scaffold and MaterialApp.

@ScottS2017 commented on Fri Dec 08 2017

I hadn't realized that we could look there but I will from now on, thanks!

I'm sure you know that the comment about Scaffold" was just a joke but if you'd have asked me about it last week, I couldn't have answered it.

I'm a subject matter expert in an unrelated field and one of the things I realized is that all experts have a hard time remembering what it's like to be totally new... so new you don't even know a basic term like scaffold. It can seem like it's a lifetime or two ago. What I'm trying to do with this thread is show you what the super-shiny new people are thinking as they go through the steps.

Speaking of, I put up another issue about docs regarding the way things are phrased. If you haven't already, please give it a glance.

You all are doing great so far and I'm really enjoying this! Just for general consumption, here's something my old mentor pounded into me:

"You have to remember to never get annoyed. This isn't the same idiot asking you the same stupid question for the one hundredth time. This is the one hundredth intelligent person asking you the same beginner's question for their very first time. I don't care how tired you are of answering it. Take your time and answer it completely, in a way that allows them to come away feeling that they understand now. That's the job. If you don't like it then step aside and let someone else teach."

@InMatrix commented on Sat Dec 09 2017

@ScottS2017 Thank you for trying Flutter and reporting your first experience here. We're aware of the Hot Reload vs. Restart confusion, and we're investigating ways to help users better reason about them and recover from errors.

We have done some user studies in which we observed how people use Flutter, but we haven't done that with users who're completely new to software development. So there are some assumptions in our docs and tools not optimized for true beginners. We'll announce our future user studies on our Google Group. Please join the group, if you're interested in receiving those announcements. Thanks again for your feedback!

@LarkAscending commented on Sat Dec 09 2017

@ScottS2017 how did you hear about Flutter? What do you want to build with it???

@ScottS2017 commented on Sat Dec 09 2017

I ran across a youtube video on Flutter while I was looking for Kotlin Android tutorials. At the moment I want to train for a second career in mobile development after a fairly long career as a Field Engineer / Repairman on a wide variety of electronic and electro-mechanical systems. I figure it's a way to exercise my creative side while not allowing entirely too many years of problem solving experience go to waste. Sadly, the career change isn't voluntary. The body just can't deal with climbing on, under and over all sorts of machinery anymore.

I figure Flutter will be a large advantage that can outweigh the disadvantages of being an older person entering this field. It's not as if people familiar with Flutter can be found on every corner. I just wonder if I'd do better for myself by coding or going around to corporations conducting training for companies that want to be able to develop for ios and Android with just one team.

@LarkAscending commented on Sat Dec 09 2017

I've always thought Flutter would be ideal for someone with your background (technically savvy, no mobile development experience). And I know it's possible to learn mobile development via this path. This is really motivating, thank you for engaging with Flutter as a contributor and sharing how you got here!

We're considering making a real entry-level codelab, something like this. We'd like to explain more high-level concepts, and make the code modular so you just import a piece of code and run it, then get an explanation of what it does. Assuming we go ahead with that project, it would be great to get your ideas and review.

@zoechi commented on Mon Dec 03 2018

Is this still relevant? Could someone summarize what needs to be done? (what is the conclusion of the discussion)

@InMatrix commented on Mon Dec 03 2018

The first comment could be a useful for improvements to hot reload error messages, so I added a t:hot reload label here. The second post seems to ask for a small tweak in the codelab? Cc: @sfshaza2

zoechi commented 5 years ago

Copied here for the codelab improvement suggestions

kwalrath commented 5 years ago

Affected codelab: https://codelabs.developers.google.com/codelabs/flutter

We didn't plan to update this codelab, but I'll look into statistics to see whether people are using it, and how far they're getting. Unfortunately, this codelab's source code isn't in this repo, so it's not community maintainable.

sfshaza2 commented 4 years ago

OK! I am about to publish an update to this codelab (in the next day or few). I have incorporated Scott's suggestions, so I'm going to close this. Thanks!