Improve documentation and official website

[chrislearn]

• Add more example code to the source code。
• Newbies to the cors function are prone to encounter problems when using it, and the documentation especially needs to be improved.
• The documentation of openapi is still very incomplete and needs to be improved.

[josejachuf]

Add more about handler error, please. Use the thiserror and others

[CharlieBytesX]

Hello! In which topics of the documentation you need contributions?

[chrislearn]

@CharlieBytesX
There are many areas for improvement

• The current documentation of many middlewares simply gives example codes, but does not explain in depth how to use them.
• The OpenAPI documentation is not perfect

In short, I hope that the documentation can be more friendly to novices and make it easier for everyone to learn and use. Any optimization and improvement of the documentation is welcome.

[CharlieBytesX]

Thanks, do you have a standard for pull requests? Would like to help next week, where is the docs web page repo? Are you talking of internal code documentation or the web page documentation?

[chrislearn]

https://github.com/salvo-rs/website

This is the website repo, you can give PR to this repo.

[abuffery]

Hi,

First of all i would like to thank you for the documentation, i am finding it very helpful in my journey, more so than others.

I would like to share my general view on documentation and an idea regarding Salvo documentation.

An issues i find with most documentation, on anything, is that they use concepts and terms in slightly different ways, making them sometimes misleading or more difficult to understand in the context they are being used.

Another issue, barrier, i find is that some frameworks have an opinionated structure of folders, file names, etc, while others have almost none. Both these approaches produce friction, either by having to rewire your brain to another structure and get used to it, or uncertainty of which is a good, valid, approach for the structure based on the framework.

Everybody that arrives to Salvo either is new to backend or coming from some other backend framework, I guess for Salvo coming from some other backend is probably most frequent.

I have found Salvo intuitive and flexible, such that I have decided to start to mimic, to the extent possible and the easiest way possible, the folder structure, file names, generators that are used in Elixir Phoenix projects basically using simple bash scripts. The main motive for me to do this is to avoid as much as possible the cognitive load i have when switching from one project to another.

When learning a framework via documentation the same cognitive load exists.

So the idea is to include in the documentation a section for newcomers from other frameworks, be they rust or other language frameworks. The section for newcomers from other frameworks could offer something like what i am setting up, a folder structure, namings, basic tooling, etc they are familiar with to get started and maybe less something with bells and whistles like the Loco framework that mimics Ruby on Rails.

Most people would probably be familiar to some degree with at least one of the frameworks listed, if they are several, and seeing something you are familiar with and maybe like or liked at some point in time, is always a warm welcome.

I see people moving from Actix to Axum, so in this sense I guess these would be nice frameworks to have, but they are less opinionated on structure and maybe each person has their style.

Outside of rust, maybe Gin from go, then we have the typical Django, Laravel, RoR, Spring, etc.

Once i have finished with the Phoenix Salvo "clone" I would be glad to let you see it and I believe maybe it is easily adaptable for other frameworks since it is based on basic bash scripts.

And if you like the idea i could help setting up the documentation for the newcomers from Phoenix for example.

Thanks

[chrislearn]

@abuffery

Thanks for your advice.

We have another project called salvo-cli, which tries to provide a template for beginners who are just starting to use salvo. It is just very basic now.

If we have the energy later, we may provide more templates to help beginners quickly create projects.

[abuffery]

@chrislearn

Thanks, I will have a go at salvo-cli