Hacker News Reader

Comment by alpaca128 | Hacker News Reader

Seems great, but I don't find the "Quickstart" section helpful. A demo video that shows 2-3 unknown commands without context is not a guide, same with links to the full documentation. Both make sense on the landing page, but both don't tell me how to get started quickly.

Edit: interestingly the restic repo's Readme is better in that regard. It's the demo video but in text form with explanations: https://github.com/restic/restic#quick-start

View on HN

Quickstart:

    repo=/mnt/mybackupdrive/somefolder
    restic init -r $repo
    restic backup /my/files -r $repo
    restic mount /mnt/backedup -r $repo
    cp -r /mnt/backedup/snapshots/latest/accidentally-removed-directory ~/restored

Where the repository can also be sftp or various other things.

There are a ton of other commands and options, but to literally just get started, this is all you need for making and restoring data from a backup.

Same goes for S3 support, working great. Been using MinIO and SeaweedFS as target, works identical to native AWS.

> unknown commands without context is not a guide

This quickstart assumes some context that not every person starting to use Restic has. It could be improved by offering some more context for each line:

    # RESTIC QUICKSTART FOR LINUX

    # Choose were you want to save your backups

    MYREPO=/mnt/mybackupdrive/somefolder

    # Initialize a new restic repo at your chosen backup location

    restic init -r $MYREPO

    # Backup your files to the newly created repo

    restic backup /my/files -r $MYREPO

    # To restore a backup, first mount the repo

    restic mount /mnt/backedup -r $MYREPO

    # Browse the latest backup at /mnt/backedup/snapshots/latest

    ls -la /mnt/backedup/snapshots/latest

    # Copy the files you want to restore out of the repo

    cp -r /mnt/backedup/snapshots/latest/directory-to-restore ~/restored

> > unknown commands without context is not a guide

Quick start != guide, to me. A guide will guide you through thing at a slow pace, a quick start is the quickest way to get something running/started. And the commands seem fairly self-explanatory, but I could be suffering from the so-called curse of knowledge.

That's fine, but 'quick' can still tell you what you're doing.

Fwiw, I've used restic for a few years, and (still, if perhaps less) agree the docs are not great.

I don't remember really having that issue, though I don't remember the very first use. I think the only time where I remember being a bit confused, was with the 'forget' command, and I would guess that's just because of its nature rather than due to lacking docs. Testing what I thought was correct with --dry-run solved that problem.

Mostly I just use restic --help or restic subcommand --help anyhow, rather than the docs. Perhaps I'm just not doing fancy enough things with it and that's why I didn't run into edge cases yet where it lacks documentation?

It is never encouraging when I see that a project is at least 6 years old and has unapproachable documentation like you describe, and language about how they'll stop changing the backup format "when 1.0.0 is released."

Like...maybe it's time to stop working on new features, and focus on a release.

Duplicati has a similar problem. They're endlessly tinkering with new features instead of squashing bugs and meeting user expectations. I think it still chokes and permanently corrupts backup archives if you interrupt it during the initial backup.

Like: guys. People expect backup software to be able to handle interruptions and disconnects. It's actually one of the things I liked the most about Crashplan, and it could handle being interrupted without issue...nearly a decade ago.

Reply on news.ycombinator.com