Rework README

[bbenne10]

After writing all of this, I noticed #52. I'm happy to work in some of the changes from that PR too, but the changes there feel excessive (and I wouldn't want to pull in the shell-script changes).

Frankly, documentation on this script is a bit of a mess.

There's haphazard attempts at showing how to get hosted platforms working with the script,
but two of the three are the same incantation but with slightly different logging params.

There's no note of how one should log in after the install runs to completion.

The nix-channel in use is now out of date.

There's nothing fundamentally unfixable though.
I am working on a fork whereby the README would be restructured.

Changes I am considering for the README:

• DigitalOcean becomes the default platform.
• Other platforms are mentioned "lumped together".
• Update the suggested channel to 20.09 (soon to be 21.03, I suppose - but that's an easy fix)
• Generic section about deployment notes
  This gives us an area to talk about the various "gotchas", but so far it'd contain:
  • Root user password vs authentication key (which has been brought up before as an issue, but was not documented)
  • grub bootloader issues (I personally needed to set boot.loader.grub.devices to nodev before nixos-rebuild switch would work)
• A table containing hosts/os/notes (which allows us to add per-provider notes without bloating the wording of the README)

[bbenne10]

Are there any thoughts on this? Or should I just go ahead and open the PR?

[elitak]

If it reduces the number of lines in the script, I am probably for it. I'd like for the entire script to be self-documenting, but asking users to read more than the first 10 lines of the comment header is unrealistic, I think, so everything must be succinct.

[bbenne10]

I agree that the script itself should be self-contained and descriptive. However, this is discussing the README, which shouldn't have an effect on the script itself I dont think.

[elitak]

Anything can go in README; I just don't think 90% of users will ever see it, since they curl the main script and don't bother installing git to clone the repo onto a doomed system. Maybe I'm way off with my estimate.

[bbenne10]

Repeat users may not. First time users should get a bit of of a gentler introduction to what's going on, I think.

For instance, I got caught by the need for an authorized key for the root user the first time I ran through.

Its obvious now, but without a password defined in my nix configuration and no ssh key, I was locked out and needed to reprovision and start again. A note in the readme would've helped here.

Further, there's not much clarity on what the script does for non-digital ocean hosts without reading the script fully. Both other hosters aren't special - they are just default runs of the script with small differences to the log treatment.

I'll work this PR up in the morning and we can discuss specifics rather than these generalities.

[bbenne10]

Closed via #67