Open chonghorizons opened 2 years ago
Copied from the v8 fluttertodos tutorials discussion. https://github.com/chonghorizons/bloc/pull/1#issuecomment-999970753
These are non-blocking comments but should be considered for a future style guide:
Codelabs by Google and other online courses use //1 and //2 etc to indicate individual lines of code. A reader who understands wont need it. But readers who are learning use it. @marcossevilla removed some (but maybe not all). I think we keep them and encourage their use. Wdyt?
A user made an issue, I think, that the file directory structure should be given. A reason is because if they are working through the tutorial, they need to know where to put files. @marcossevilla removed them. Wdyt? I think they are ugly, but they are helpful. See #1758 from Sept, 2020.
For long tutorials like this, do we want an early discussion of architecture or overview of the strategy? When tutorials jump straight into code, it skips an important step of the thinking process that an actual programmer uses to start. Wdyt?
Decide on whether the target audience is beginners or more advanced programmers. It seems like the tutorials are aimed for advanced programmers, but a bunch of the questions that come up are more beginner.
It may make sense to leave the main tutorial as more barebones, like a "code tour" aimed at seasoned programmers, but have additional content like a Medium article that is longer and is aimed more at beginners.
Nits mentioned elsewhere:
Use includes to the codebase directly? Or use snippets to a saved snapshot.
Use sh rather than shell for markdown code snippet.
Should headers be filenames like "edit_todos_bloc.dart", or just "bloc". If they are filenames, this removes ambiguity because there are many blocs. (Also allows clearer internal anchors for hyperlinking)
There's a question of how to include widget tree-diagram structure in documents. Currently these are some options:
Example
Example
Root
--RepositoryProvider<TodosRepo>
|--MaterialApp
|--Home Page
| |--BlocProvider<HomeCubit>
| |-- ...
| |--IndexedStack
| |--TodosOverview
| |--
| |--
| |--
| |--Stats
|--BlocProvider<EditTodosBloc>
|--EditTodosPage
|--
Use an interactive widget tree in the docs itself. This might be via an embed so that docsify
can still be used.
One possibility is to use a lightweight package like jstree
, see http://jsfiddle.net/gdonarum/2Jg3B/
One still needs to figure out and take a manual step to output the JSON for the widget tree and then load the widget tree.
Advantage: interactive in the docs Disadvantage: Have to write (one time) the tooling to generate the widget tree as json. And the code to generate the embedded clickable tree.
Note: One could use multiple methods. Like a simplified ascii tree (option2) , and then a link to a Devtool screenshot (option1).
Hey @chonghorizons, I just want to mention something that I believe is relevant - 'Prefer working software over comprehensive documentation.'
Over the past year, the face of the bloc api has flipped back and forth numerous times, making it really hard to keep up with all the changes in the documentation.
At first, I felt just as strongly as you did about updating the documentation, @felangel was no stranger to my recommendations, and the one thing that we decided to prioritize above everything else was making sure the examples themselves were relevant, up-to-date, working well and fully tested.
In some ways, that means we are relying on the code itself to be self-explanatory, and Lord willing, as we fine-tune the api, this will be the case.
I share this with you because I really appreciate all the contributions you are making, and I agree that we are missing a high-level architecture discussion
- do we want an early discussion of architecture or overview of the strategy?
Instead of doing this for every single tutorial, I think it would serve to do it once very well so that we can more easily maintain every other exapmle
@Gene-Dana thanks.
I'm getting a sense of that too. Working code kinda self-documents.
I think the docs work well for experienced programmers, but isn't so good for people who are new or get stuck.
So, I think the tutorials can offer optional things. Like @jeroen-meijer has mentioned recently. Like a quick q&a that people who want to read can read, but that experienced programmers can just skip.
Offering optional extras doesn't slow down the docs (which I think is good, it keeps it lean). But it makes a big difference if someone gets stuck or needs a bit more handholding.
I'm wondering how we can implement the QA without too much overhead and with flexibility. Perhaps something with threads on the discord??? Channels for each example perhaps?
@felangel the more I think about this the more I like it. A channel for each example with archived threads! We can still triage and support others like normal, although an example support section could be useful
Also I think we need a repo channel!
@chonghorizons are you on the discord?
@chonghorizons are you on the discord?
Yes. Hocho on discord. I am active in documentation channel.
@felangel the more I think about this the more I like it. A channel for each example with archived threads! We can still triage and support others like normal, although an example support section could be useful
Discord is great for interactive. But it isn't search indexed and isn't easily discoverable. So, if something on discord is really helpful, putting it on a GitHub-repo on a wiki makes sense. The repo might be "BlocExamplesDiscussions".
Even better. If someone gets helped, recommended homework is to do a short wiki writeup for that repo.
@Gene-Dana
Current state on the Architecture question in tutorials:
architecture
section of the docs that covers all tutorials, and each tutorial links to. todos
example, some discussion of Architecture is recommended, at least for advanced tutorials. (See copied snippet below).Architecture
- The architecture of this tutorial is believed to be straightforward. Read the
Architecture
section. Good Architecture can be more than 50% of a project.
- The architecture of this tutorial is complex. First, read the
Architecture
section, which covers the general principles. Good Architecture can be more than 50% of a project. In this case, the following non-trivial architectural decisions were made.- [Insert list of non-trivial architectural decisions, or discussion of data-flow]
- [OPTIONAL: Link to separate MD file with longer architectural discussion]
RESULTS/PROS and CONS:
ALTERNATIVE:
Copying some comments about architecture form another issue/thread.
I think the tutorial is great, especially the app layer with state management! Great job!
I had two major comments though that I think could be super beneficial:
Explain the high-level architecture of the project, and why we took that approach. Otherwise, I can imagine the first question for many people will be "what is this repository and this API package?". A common topic that we have seen in the past is that many times repositories are simply wrappers around data clients, and this project is a good example of that. I think it could be very beneficial to explain a bit more in detail the purpose of the repository, in this case, trying to explain the benefits that might bring if more changes were needed in the future with new features, so the reader as a better understanding of its purpose.
Source: (https://github.com/felangel/bloc/pull/2859#pullrequestreview-844975752, @jorgecoca)
- If I understand correctly, @marcossevilla and @Gene-Dana (in docs(flutter_todos): add new flutter todos example #2859 and this issue) aren't as much in favor of including a section on Architecture in each tutorial, preferring (only??) a central
architecture
section of the docs that covers all tutorials, and each tutorial links to.
I think the best approach is to give the general architecture concepts or practices that are used in a specific tutorial on the architecture section and then link to the tutorial to see those concepts applied in code. For example:
Let me know what you think. 👍
UPDATE:
@felangel is rewriting the Architecture section.
I reviewed what @felangel merged this past week for the todos
example.
@felangel doesn't currently link back to Architecture for todos
. He is more verbose, going over
data layer
domain layer
feature layer
See the Architecture section he pushed this week, and the diagram he included. That diagram is pretty important, IMO. And, just above, he links to Single-responsibility_principle, which I think is very important and helpful to reinforce.from https://bloclibrary.dev/#/fluttertodostutorial?id=architecture
Some of what is in the todos
tutorial is general and could be moved to a central discussion of that pattern. (The central Architecture hasn't been changed yet. https://bloclibrary.dev/#/architecture)
- If I understand correctly, @marcossevilla and @Gene-Dana (in docs(flutter_todos): add new flutter todos example #2859 and this issue) aren't as much in favor of including a section on Architecture in each tutorial, preferring (only??) a central
architecture
section of the docs that covers all tutorials, and each tutorial links to.I think the best approach is to give the general architecture concepts or practices that are used in a specific tutorial on the architecture section and then link to the tutorial to see those concepts applied in code. For example:
- Architecture: {pattern} is used when {explanation}. See [examples].
- Example 1: In this example, we use {pattern} to {explanation_for_example_1}.
- Example 2: In this example, we use {pattern} to {explanation_for_example_2}.
Let me know what you think. 👍
Interesting. I'm trying to understand what you are proposing. @marcossevilla: Is this correct:
Or, do you mean:
@chonghorizons I'm planning to update the central architecture section this week so that we don't have to repeat generic architectural best practices in each tutorial. I'd prefer the tutorials to only contain the information relevant to the tutorial and link to various sections for more general concepts like architecture.
Copying a piece of feedback from https://github.com/felangel/bloc/issues/3121#issuecomment-1008362831
Even though the architecture tutorial gives an abstract overview of BLoC architecture and the app tutorials (especially the new flutter todos example give examples of simple implementations, there are not many resources on architecting a more complex app with multiple BLoCs and a repository and how they should communicate. This would not require going over the code, just examples of architecture diagrams of BLoCs and a Repository (+API) and how they communicate, ideally for a variety of different apps.
Description
This is an issue to track and discuss style guide issues about tutorials.
This might including