Comments on the documentation

[happysalada]

Hi, first of all thank you for this great project! I used phoenix for about 3 years, and I love that someone is trying to port the good about phoenix to rust!

I have a couple of comments on the tutorial, not sure if you want to separate them into new threads, so I'm putting them here.

• I quite like that you are helping with the choice of which runtime to start with (pushing for smol at first). I would if possible add a couple of pros and cons. In my mind for example if you want to run with a db with for example sqlx, you are going to need tokio or async-std. I think mentioning that in the choice, would be nice. So something like.

If you are not sure where to start, trillium_smol is a good place to start. It's easy to switch later on. If you need to interact with a db (with for example sqlx), you are going to need tokio or async-std.

I would even want some more nudging relative to tokio or async-std, but I'm not able to write the nudge part :-)

• since working with a db involves choosing an tls acceptor, I would love to have some nudging regarding which one to choose between rusttls or native-tls. (sqlx doesn't really push you in one direction or another). I feel you might be able to skip this choice at first (I might be wrong).
• In the tutorial sometimes you rely on external crate (when introducing logger and env_logger for example). It would be nice to have just a heads up about running cargo add trillium_logger env_logger for example. The crate name has an underscore, where the library has a -. It's a detail really, it provides just for a smoother experience, feel free to ignore.

[jbr]

This is an interesting point — I agree it might be worth saying something like "If you need to use sqlx, you will need to choose between async-std and tokio." I won't point to either of them because at this particular moment in time, they each have major flaws. I will also take a look at trying to convince the sqlx folks to add an async-global-executor option, which would work on async-std or smol, as they both use the same underlying executor.

Your feedback on docs is very helpful, valid, and appreciated! I'm trying to write for a range of experience with rust and web frameworks, and it's easy to lose track of the different readers. Could you write a little one-sentence simplified "persona" with the background you're coming from? Doesn't need to be exactly you, but it would be useful to know stuff like: Experience with rust (is this your first rust project? Tenth? Should I be explaining other "getting started with rust" stuff in the docs?) and experience with async rust (the point about sqlx is a good example of something I wouldn't have thought to point out, are there other things I'm assuming familiarity with?). Might be useful to also understand what other web frameworks you're familiar with other than phoenix, although phoenix/plug will definitely be the closest fit. I intend to ask other people this as well to better understand what type of documentation to include, and might even turn this into a little form.

Thanks!

[happysalada]

I've playing with rust for a while, doing lots of tutorials, reading about it. I have an OK grasp of the language, but I have no async experience. I read the tokio tutorial out of curiosity, but I don't have an overview of the different libraries and their strengths and weaknesses.
In terms of framework, I've played with actix, but I don't also have an overview of the advantages and disadvantages of rocket, actix, tide, warp... I came to trillium because I thought the syntax looked so simple.
In terms of web experience, I've done Phoenix for 3 years, and while I loved it, I always felt the types where more of an afterthought than really part of Elixir. There is Gleam that solves the types problem, but I really want to give rust a good try and be able to say if it is "too low level" or if it's just a matter of habit in order to be productive with a type system.
So first rust project, I don't expect you to explain any of the getting started in rust stuff, but definitely some informations about the eco-system will not be too much! :-)
Let me know if I forgot anything.

[jbr]

Thanks! Your feedback is incredibly useful to me — you're precisely the sort of developer I'm making trillium for. Please continue to let me know what's even a little bit confusing or counterintuitive, it's a great help!

[happysalada]

will do! Thank you for your positive feedback!