Make documentation great

[mskorkowski]

In Relm4/Relm4#46 (comment) @AaronErhardt rised an issue with documentation being hard to understand

I only felt like the book is a bit hard to understand.
Maybe the concept would be easier to understand if you take a database (that needs an unique ID for entries) as metaphor thinking

Let's keep the discussion here

[AaronErhardt]

I found it hard to understand the meaning of different parts of the application and how they fit together. Some aspects are relatively familiar from factories but on the store side I found it hard to follow. Maybe we can find a metaphor from the real world to make it easier to understand. At least that's usually what helps me and what I used in the Relm4 book (for example in chapter 1).

[mskorkowski]

@AaronErhardt I've updated the application architecture chapter in the book by adding "How does it fit into my relm4 application" section. Can you check it?

https://mskorkowski.github.io/relm4-store/beta/book/04-application_architecture.html#how-does-it-fit-into-my-relm4-application

PR #36

[AaronErhardt]

I like it. But isn't a store view rather something like this in database analogy?

SELECT FROM data_store WHERE changed=true;

[mskorkowski]

No it's not.

SELECT FROM data_store WHERE changed=true;

would mean that we only show values which were updated. In pseudocode view is something like this:

while true {
  await data_store.changed();
  view = SELECT * FROM data_store LIMIT view.start,view.page_size;
  for record in view {
    if record.has_changed() {
       update_ui(record);
    }
  }
}

[AaronErhardt]

Ok, thanks for clarifying. If I'm correct the store view does two things then:

1. Select the elements that should visible and on the current page
2. Render the visible elements efficiently

Maybe something like this could be put into the book for each part. Just bullet points of what a part is responsible for.

And I just remembered that I had problems to understand the graph of the relm4-store architecture. Maybe it's better to make a graph without the regular update function that only focuses on relm4-store. Otherwise the arrows are a bit confusing. And it should be obvious that you can still use the normal Relm4 architecture for the rest of the application.

Or actually, you only need to adjust the first graph that shows the Relm4 architecture. Just move all components to the same place as in the second graph so it's clear that the second graph is an extension of the first one.

[mskorkowski]

I've released new prerelease version of the book under https://mskorkowski.github.io/relm4-store/prerelease/book/index.html

It contains updated mvc diagram for relm4

Also in todo_1 application in first three chapters I've added short description at the top of the chapter what it is

• Model/Record
• Store
• Store view

@AaronErhardt when you have a bit of the time can you check and tell me what you think about that?

Extras

I've also started working on the storenomicon where all the "too much of the detail" should end up.

Prerelease version of the book is because I found a few bugs in the beta.2 and the book already contains updates related to that. No example was harmed in the process.

[AaronErhardt]

Feels much better to read for me. Well done!

I also like the idea of the storenomicon. It could also be part of the book in later chapters but less details upfront definitely make it easier to understand.

There's one thing I noticed (I hope I can have a closer look this weekend):
The list of imports is a bit intimidating, for example: https://mskorkowski.github.io/relm4-store/prerelease/book/examples/01-todo/03-task_list.html#list-of-imports
I know that's personal preference, but could you maybe make them more compact and readable by using brackets?