Consider rewriting documentation introducing tapir to newcomers

[adamw]

• gather feedback from newcomers to tapir, which parts of the docs where helpful, and what was missing
• rewrite / split / expand / reorganize depending on the outcome of the above

[peterlopen]

hi,

I personally had hard times with following points:

• every in/out method on endpoint will modify type signature of serverLogic method and makes respective inputs/outputs available. Fighting with types on copied examples did not make this link immediately obvious.
• error handling - again, type fighting and until I found this example https://tapir.softwaremill.com/en/latest/endpoint/oneof.html#error-outputs I was not able to compile my endpoints and assume I will be somehow able to return those errors from endpoint logic. still, I am not sure what it is doing and maybe it is not what I want.
• Either in serverLogic signature (which makes perfect sense) is another surprise adding to type complexity.

Probably my approach - taking complete endpoints from https://github.com/softwaremill/realworld-tapir-zio and modifying them to my needs - was not good one, as I end up dealing with fairly complex types and lots of type errors, missing basic understanding what I am dealing with. Still, I found documentation more just describing the implementation then providing guideline how to get working sample with principles behind it explained (which is fine I guess, we have chatGPT and SO for that nowadays /s)

thanks.

regards, peter