Add a written quick start

[simonsan]

Discussed in rustic-rs/rustic#797

^{Originally posted by xpe August 5, 2023}
Video quick starts may be hip, but written ones are preferable for these reasons:

1. people read at different speeds (watching a video is painfully slow for me)
2. it isn't practically feasible to skim a video
3. copy-paste (I wanted to copy-paste the example config file)
4. written docs are easier to edit and therefore maintain.

Thanks for this project. FWIW, my criticisms about video walkthroughs are universal and not particular to this wonderful project! 👍

[simonsan]

Quick note: A possible written quick start could be based on the autocast yaml file as a starter.

[simonsan]

For rustic_core quick start, we can also create a tutorial like winnow does: https://github.com/winnow-rs/winnow/tree/main/src/_tutorial

It's basically another module and docs.rs being used to render it:
https://docs.rs/winnow/latest/winnow/_tutorial/index.html

[simonsan]

Given we have now a separate repository, I think the winnow approach is not viable anymore. We should just write a good old Getting Started. The current terminal one can be found here with a note https://rustic.cli.rs/docs/getting_started.html.

[pflakus]

I liked the idea of having the session as an asciinema-cast and wanted to play around with the autocast project @simonsan suggested. So I went ahead and created a .yaml- and .cast-file that emulates the original session from the video recording.

---

(Apparently GitHub doesn't play nicely with filetypes it doesn't recognize. But it's fine with .zip-archives, so that's how we're doing this.. 😉 )
I put the following files into this archive:

• getting-started.yaml is the config I used to run autocast from
• getting-started.cast is the resulting asciinema-cast

You can revise my version before it is pushed to the asciinema website, so the version for the documentation looks as nice as you intend it to.
Hope this helped. 😃

[aawsome]

@pflakus Thanks for your effort! I fear you missed that the video was already created by asciineema, see https://github.com/rustic-rs/assets/tree/main/getting_started - I must say, this is not really obvious from the docu website and have to apologize if this meant you redoing some of the work..

If you have improvements, please open a PR on the assets repository - we can also include the cast file there or add some auto-generation which we can run when rustic changes...

For the topic of this issue: It is about adding a written getting_started additional to the present aciineema - which allows users to read at their own speed and makes copy&paste easier. So any help with this is highly appreciated!

[pflakus]

I see. No hard feelings, it was a small effort and a learning opportunity for me anyways, as I said. 😃

I think uploading the cast to asciinema.org and embedding it is a decent solution/compromise. It enables the user to pause as well as select & copy content from the shell, which covers the issues you mentioned with the GIF version.

If you still prefer this introduction to become a write-up anyways, I'm happy to push a PR for that instead. Just let me know how you think it ought to look.

[vwkd]

Also linking to the asciinema recording in addition to embedding the GIF would be great, which allows readers to pause, resume and skip as well as copy and paste.

[simonsan]

@jvasile 's written getting started guide has been merged: https://rustic.cli.rs/docs/getting_started.html

If there are any additions/fixes to make, please feel free to make a pull request. I'll leave this issue open, for some more ideas.