Improving user experience in documentation

[abelardolg]

Is your feature request related to a problem? Please describe. A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

• To begginers, it's difficult to visually represent the concepts managed in the demos or, even, in the core concepts section.
• We have difficulties to know what the structure of each demo (tutorial) is.

Describe the solution you'd like A clear and concise description of what you want to happen.

• To show a diagram (class diagram, sequence diagram and so forth or visually more attractive) to represent better the architecture of each contained demo in the tutorial.
• To show a tree structure of the project above each code to indicate where this code lives.

Describe alternatives you've considered A clear and concise description of any alternative solutions or features you've considered.

• Show a diagram with boxes where each box represents a class/module which is contained into the application.
• Show a tree diagram above each code to indicate the folder of that file.
• Each file should have three tabs: architecture (it shows how this module interacts with others); tree (it shows which folder contains this file); code (it shows the code itself along with your comments).

Additional context Add any other context or screenshots about the feature request here.

• When an user clicks over on each box inside the diagram, it should show the tree/code of that file/box.
• When an user clicks over on each tree diagram, this should unfold the minimalist version of this tree showing the location of this file under the tree.

Best regards.

[abelardolg]

One question, please: What's the technology behind your doc? It's very terrific!! Congratulations!

[felangel]

@abelardolg thanks! The docs are currently built using docsify

[omidraha]

What's the meaning of ✨ beside some topics?

[felangel]

It means those tutorials have been revamped and are following the latest best practices

[lhmzhou]

@felangel Can you recommend resources on best practices in Flutter/Dart, whether it be in book form, wiki pages, or learned lessons from your experience?

[chonghorizons]

@albertodev01 I had the same frustration with tree structure and widget structure. I am writing a draft of the docs for the updated flutter_todos tutorial. (not up on the website yet, but the markdown file exists)

Addressing two of your points:

• Directories: https://github.com/chonghorizons/bloc/blob/chong-docs-todos/docs/fluttertodostutorial.md#directory-structure
  • Did you know... the full source is in github, so you can look at the directory structure there. For example: https://github.com/chonghorizons/bloc/tree/chong-docs-todos/examples/flutter_todos
  • I always have the source code open in Android Studio or github when I read the docs.
• To show a diagram (class diagram, sequence diagram and so forth or visually more attractive) to represent better the architecture of each contained demo in the tutorial.
  • Take a look at https://github.com/chonghorizons/bloc/blob/chong-docs-todos/docs/fluttertodostutorial.md#widget-tree and
  • https://github.com/chonghorizons/bloc/blob/chong-docs-todos/docs/fluttertodostutorial.md#commentary---event-flow

Do those address some of what you are looking for?

If these help and you want more, please let me know. I'm toying with the idea of making a short video called "how I start the first 30 mins of a tutorial".

[chonghorizons]

@felangel Recommend closing this issue or labeling as "waiting for response" Because I'm tracking it at #3086.