Onboarding Docs are seriously anti-"Production Ready"

[goyalyashpal]

Titles:

• Onboarding Docs seriously anti- "Production Ready"
• Show OOP style in py-getting-started & direct towards a particular tutorial at end

Situation

• Just discovered this: Reusable UI Components
• after seeing class based flet UI tutorial on video: iYP6l1FYd-Y by "Mr. Newton"

Prior to this,

• I had completed the Flet Introduction, and Python Getting Started
  both of which show the flet-app done the procedural way.
• thereafter, i tried to use flet to make actual app; using Controls Reference side-by-side as needed
  this also lists instructions in POP way
• that is, the OOP way doesn't even get any mention anywhere to a newcomer
• I had almost given up on flet due to this completely POP approach
  which became impossibly hard to even grasp on trying to apply.
• and I did started doing Flutter
• ... which starts at this tutorial: first-flutter-app which teaches things the OOP way right from start....

Problem

Point I am trying to make is:

• this flow of docs given below does NOT make any sense to a newcomer.

• it first teaches it all in the POP way, then doesn't even mention about OOP way,
  and leaves the learner hanging in between.
  only for per to eventually decide it's too complicated to manage, and leave.

• the person is not guided towards a particular proper tutorial at any place.
  the tutorials don't have any order numbering, nor a "start here" label at the tutorial picker page.

• even the tutorials - I am assuming the Python - To-Do to be the first one -
  starts again from scratch from installing flet; a step already covered in the introduction

• oh, and the "how-it-works" doesn't even get any surface it seems.

- "0. Introduction"             (example 1: counter :: POP)
> "Tutorials > Want to learn how to build a real app?"
(tutorials? yes yes, sure please :))

> "1. Py Getting Started"       (example 2: Name input :: POP)
(hmm, Tutorial & Getting Started, sounds same :D let's proceed :))

> "but it's a matter of personal preference :)"
(umh, is that it? doesn't feel like it.)
(wow, such an abrupt stop! where to go next?)

> "Testing on iOS"
(whattt? oh it's flet-python documentation)

> "Tutorials"
(so many, umh which one to pick now??)
<trying randomly>

> "Python To-Do"
(OOP - the right way) ...

Let's Talk Solutions

1. show the how-it-works inside introduction to showcase those advantages to the technically acquaint person.
2. move the Flet app example and below sections from introduction to a new (next) page with "minimal" added in the title.
   smth like "Flet app minimal example" or "Flet minimal example"

3. [SALT]: Are you sure about the planned "multilanguage support"?
   This will make docs etc a lot more involved and require lots of redundant/repeated work.
4. [cntinued]: If yes, then some way to compile to different targets seems worth trying.
   See shen Yggdrasil - it will cover python, C/C++, JVM (java vm), JS (JavaScript), & Lisp in one go.

5. [Anyways, B2TT]¹: Add a successor page (or section) to py-getting-started aimed at converting the POP code obtained at that point into OOP styled; and move the reusable-ui-components at this new page's top.
6. At the end of this new page, refer to one particular tutorial - say, the python-todo
7. At the end of that (now designated first tutorial), refer to the tutorial picker page.

Footnotes

1. back to the topic - an abbreviation i just coined on the fly lol. don't know if it's real in the wild web. ↩

[FeodorFitsner]

Thanks for your feedback!

So, you feel OOP way would be more preferable by fellow developers vs POP way?

Re: "multilanguage support" - that was the "grand" idea - to allow doing Flet from multiple languages, but currently it's unreachable goal. Python is so huge and adopting Flet for a different language is like starting all over again.

[goyalyashpal]

you feel OOP way would be more preferable by fellow developers vs POP way?

yes, the reasons

• can't be put in better words than the Flet documentation itself:
  reusability, clarity & manageability.
• it also makes it more inline with flutter.

website/docs/tutorials/python-todo.md

Lines 124 to 128 in c5ab4c4

	### Reusable UI components
	While we could continue writing our app in the `main` function, the best practice would be to create a reusable UI component. Imagine you are working on an app header, a side menu, or UI that will be a part of a larger project. Even if you can't think of such uses right now, we still recommend creating all your web apps with composability and reusability in mind.
	To make a reusable ToDo app component, we are going to encapsulate its state and presentation logic in a separate class:

[addition:]
oh, and aside from which one is more preferable;
having an additional page will cover both the approaches
and has the potential to showcase differences with each approach (i.e. if app size is appropriate for that approach)
thus allowing the person to choose for perselves.

not to imply: tutor all different ways; rather just that POP/OOP seem to be most widely applicable ones in this domain

[FeodorFitsner]

OK, will give it a thought. Definitely, docs require improvements!