search

seed-rs / seed-rs.org

Seed's official website
https://seed-rs.org/
Other
14 stars 40 forks source link

Add a chapter for explaining Seed features #76

Closed arn-the-long-beard closed 4 years ago

arn-the-long-beard commented 4 years ago

Hey guys,

As discussed on discord, it could be nice to add some tutorial/documentation on seed-rs.org to explain major concepts such as Orders::subscribe & Orders::notify but maybe routing and other topics as well.

Since it is a chapter a bit different from just an app, I added it at the very end on the menu.

I think we need to :

MartinKavik commented 4 years ago

I'm trying to write seed-rs.org content as a book. It's a bit inspired by Rust book, where you can find the text below in the section How to Use This Book:

In general, this book assumes that you’re reading it in sequence from front to back. Later chapters build on concepts in earlier chapters, and earlier chapters might not delve into details on a topic; we typically revisit the topic in a later chapter.

You’ll find two kinds of chapters in this book: concept chapters and project chapters. In concept chapters, you’ll learn about an aspect of Rust. In project chapters, we’ll build small programs together, applying what you’ve learned so far.

concept chapters on seed-rs.org are e.g. Rust, Element Macros or especially Fetch.

This sequence of chapters is important for keeping reader's flow and don't scary them off by some advanced concepts in the beginning. Also it wouldn't make sense to introduce advanced concepts in the end when the user already knows them.

Also we have a bad experience with too small examples that demonstrate concepts for large apps - especially introduced boilerplate by Elm architecture modules in a small example was/is "very popular" among the example code readers. It provoked many comments about how bad TEA is. Another popular "topic" is routing - it looks very cumbersome in a small example and people try to improve the API. Until they try to design better API that is usable in larger apps with nested pages.

So the main goal is:

  1. Seed / Rust beginners starts to read the "book" (aka seed-rs.org content).
  2. He learns step by step Rust and Seed and how to design and architect a frontend app.
  3. Once he finish it, he is able to develop a Seed app according to the given specifications or requirements.

Those are reasons why I think we shouldn't just add somewhere a bunch of new chapters. To respect the flow, there are some places where we could place a concept chapter:

However we can add something like a crossroad/index/summary page. Or FAQ is often requested page.

I hope I've explained my reasoning why the seed-rs.org is structured as it is and why I would probably refuse to add random pages explaining some concepts. However I'm open to changes if we agree that they make sense. What do you think?

arn-the-long-beard commented 4 years ago

Hello !

Thank you so much for your post.

Also we have a bad experience with too small examples that demonstrate concepts for large apps - especially introduced boilerplate by Elm architecture modules in a small example was/is "very popular" among the example code readers. It provoked many comments about how bad TEA is. Another popular "topic" is routing - it looks very cumbersome in a small example and people try to improve the API. Until they try to design better API that is usable in larger apps with nested pages.

I do agree on that and I understand that you want consistency regarding the flow.

I will come tomorrow with new propositions :smile:

arn-the-long-beard commented 4 years ago

Okay, Then I think I should start small. There are a lot about notify & subscribe in https://seed-rs.org/0.7.0/todomvc_routing/

I will do as you suggest and make page there.

A chapter about notify/subscribe after https://seed-rs.org/0.7.0/todomvc_routing or after Time Tracker authorization (I haven't written it yet.)

Did you mean page right ? Because I am not sure what to put if I have to write an entire chapter there.

MartinKavik commented 4 years ago

Yeah, a page. I call them chapters instead of pages because they are often pretty long and once we decide to export them to something like a pdf file so users can read it offline, then each chapter will have many pages.

arn-the-long-beard commented 4 years ago

Ok thank you for your message :D

I do some stuff for hooks right now and then I go back with new proposition :)

arn-the-long-beard commented 4 years ago

Hello :)

I have been a bit busy on other parts related to seed, especially the atomic_hook and there is more work there to be done if we want to integrate it to Seed to work on performances.

I think I might not be able to commit on tutorials for seed-rs.org as I wanted in the first place.

Is it fine if somebody continue this PR ? Or should we close it ?

MartinKavik commented 4 years ago

Closing. I'm also focusing on other things now so I wouldn't be able to do proper reviews / give feedback.

arn-the-long-beard commented 4 years ago

Ok :smile:

Thank you for your message!