docs: style-guide and decisions for tutorials

[chonghorizons]

Description

This is an issue to track and discuss style guide issues about tutorials.

This might including

• visual styling
• sections to include / exclude
• target audience
• order of presentation and organization.

[chonghorizons]

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.

[chonghorizons]

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)

[chonghorizons]

There's a question of how to include widget tree-diagram structure in documents. Currently these are some options:

Option 1: Screenshot

• Screenshot of the widget tree from flutter devtools
  • advantages:
    • it promotes the use of devtools
    • the user can verify and generate the same exact widget tree
      • In DevTools, they can interact with the tree and expand/collapse nodes.
    • faster than hand-editing an ascii tree
  • disadvantages:
    • it has to be generated manually for docs
    • it contains all the widgets, which is information overload.
    • If some widgets need to be highlighted, this must be done manually. See

Example

Option 2: Ascii tree

• Make an ascii tree, like a directory tree
  • advantages:
    • easier to maintain
    • tree can be simplified, only showing key bloc relationships
  • disadvantages:
    • slow to create
    • it has to be generated manually for docs
      • May be possible to autogenerate the full widget tree and then prune it by hand, using devtools.
    • won't match the widget tree in devtools
    • doesn't promote the user to look at the devtool widget tree

Example

Root
--RepositoryProvider<TodosRepo>
  |--MaterialApp
    |--Home Page
    |  |--BlocProvider<HomeCubit>
    |    |-- ...
    |      |--IndexedStack
    |        |--TodosOverview
    |          |--
    |            |--
    |              |--
    |        |--Stats
    |--BlocProvider<EditTodosBloc>
      |--EditTodosPage
        |--

Option 3: interactive widget tree in the docs

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).

[Gene-Dana]

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

[chonghorizons]

@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.

---

[Gene-Dana]

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?

[Gene-Dana]

@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

[Gene-Dana]

Also I think we need a repo channel!

[Gene-Dana]

@chonghorizons are you on the discord?

[chonghorizons]

@chonghorizons are you on the discord?

Yes. Hocho on discord. I am active in documentation channel.

[chonghorizons]

@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

[chonghorizons]

Current state on the Architecture question in tutorials:

• If I understand correctly, @marcossevilla and @Gene-Dana (in #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.
• @jorgecoca gave a code review suggesting more description of "the purpose of the repository". I interpret this to mean that, at least for the todos example, some discussion of Architecture is recommended, at least for advanced tutorials. (See copied snippet below).
• @jeroen-meijer and I have suggested more of a need to describe Data-flow (in #2859)
• @jeroen-meijer and I have suggested short Q&A blocks or common gotchas/notes/tips (not in the main doc, but linked)
• @Gene-Dana has suggested a discord channel for each tutorial. (https://github.com/felangel/bloc/issues/3086#issuecomment-1006195454)
• @felangel is rewriting the Architecture section.

---

Possible way forward regarding Architecture

1. Keep 80-99% of the Architecture discussion in a central section of the docs (common to all tutorials). Beefed up by @felangel who mentioned a possible rewrite.
2. Always include an Architecture section in each tutorial (the other 20%-1%). It could be:

• Minimal:

  • The architecture of this tutorial is believed to be straightforward. Read the Architecture section. Good Architecture can be more than 50% of a project.

• Maximal:

  • 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]

3. Adopt @Gene-Dana 's recommendation of a discord channel for each (tutorial,version). Main docs link to that discord channel.
4. Opinionated people (like me, I admit) can write stuff in the discord channel that only people who get stuck will click through to.
5. Do not include widget trees in tutorials.

RESULTS/PROS and CONS:

• Architecture is highlighted always.
• Small slowdown in the docs (half a page).
• People who want more can click through (to Discord channel or short Q&A blocks). I.e., it gives a place for people to go if they get stuck.

ALTERNATIVE:

• Don't include an Architecture sections in each tutorial. This reinforces people thinking about Architecture too late or thinking it is not as important. And people might get stuck.

---

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)

[marcossevilla]

• 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. 👍

[chonghorizons]

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)

[chonghorizons]

• 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:

• Each Tutorial
  • No Architecture Section at all.
  • No links to Architecture (?)
• Main Architecture Section of the docs
  • Pattern1
  • Explanation, when used, etc.
  • Examples
    • Example1
      • CounterApp
      • Discussion of Pattern1 in Counter App
      • (links to relevant example code)?
    • Example2
      • TodosApp
      • Discussion of Pattern1 in Todos App
      • (links to relevant example code)?
    • ... [More examples]
  • ...
  • [More patterns]

---

Or, do you mean:

• Each Tutorial
  • Architecture Section
    • Patterns used as a short list
    • links to Architecture-Pattern
    • no extended discussion of architecture in the tutorial
• Main Architecture Section of the docs
  • Pattern1
  • Explanation, when used, etc.
  • Examples
    • Example1
      • Counter App
      • Discussion of Pattern1 in Counter App
    • Example2
      • Todos App
      • Discussion of Pattern1 in Todos App

[felangel]

@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.

[chonghorizons]

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.