nixos/doc: improve install instructions

[davidak]

Description of changes

• Update download URLs
• Replace "USB stick"/"USB Drive" with "USB flash drive" as that seem more correct
  https://en.wikipedia.org/wiki/USB_flash_drive
  https://elementary.io/docs/installation#choose-operating-system
• Don't mention CD as easiest option anymore,
  as all modern systems should be able to boot from USB,
  but many don't have a CD drive. Burning CDs is also usually wasteful as you
  can't burn them again.
• Remove link to NixOS Wiki (Making_the_installation_media) as it is not needed
• Add Etcher and USBImager as graphical tools to create install drive
• Make dd command consistent and use block size of 4 MB for faster flashing
• More consistent text
• Add instructions for "Booting from the install medium"
  Inspired by https://github.com/elementary/website/blob/9a91b0f4956b059db02122fbc738c4c067e033a7/docs/installation.md#booting-from-the-install-drive-booting-from-the-installation-medium-clear-float-2
• Add instructions for "Graphical Installation"
• Restructure headings and anchors for "Manual Installation"
• Adding legacy anchors for "Manual Installation" to not break links

---

I have tested booting from install drive created with Etcher, USBImager and dd on linux. It would be great if someone can test the other options (macOS and Windows).

I hope to get this into the release.

cc @dasJ

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandbox = true set in nix.conf? (See Nix manual)
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 22.05 Release Notes (or backporting 21.11 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
  • (Release notes changes) Ran nixos/doc/manual/md-to-db.sh to update generated release notes
• Fits CONTRIBUTING.md.

[davidak]

@samueldr thank you for the review!

[dasJ]

I find it unlikely that this will get into the release in time since its a fairly new PR touching a lot of docs and I assume more people want to review it (release schedule is for tomorrow).
That being said, I see no reason we shouldn't backport this at a later point. I don't assume a lot more people will do new installations after the 22.05 release so there's no need to hurry and more time for thorough reviews of this critical piece of docs (one of the first items a new user would touch)

[davidak]

I don't assume a lot more people will do new installations after the 22.05 release
this critical piece of docs (one of the first items a new user would touch)

i think that is a good reason to merge this big improvement before the release. two topics are not documented at all right now

it might not be perfect, but i think the experience with this change would be better than without it

do you see specific parts that can be controversial? (i will add system requirements in a separate PR)

[davidak]

@Mic92 thanks for your review!

I have incorporated all feedback.

[davidak]

Why is this still not merged?

Everyone is complaining that the documentation is outdated or incomplete and this PR would improve that, but now it's stalled for about 2 weeks. I had plans for further improvements once this is merged, but this contribution experience is very discouraging.

[thiagokokada]

A few nitpicks.

[thiagokokada]

There is also the fact that some people use awfully bad USB pendrives during installation, and this can make the boot time takes a few minutes.

[thiagokokada]

Why is this still not merged?

Everyone is complaining that the documentation is outdated or incomplete and this PR would improve that, but now it's stalled for about 2 weeks. I had plans for further improvements once this is merged, but this contribution experience is very discouraging.

Sorry, but commiters are also busy folks. And also we sometimes forget about PRs.

A reminder to review/merge a PR is always welcome, but please avoid an aggressive tone when doing so.

[fufexan]

What's the status on this PR? It's been sitting for some time.

[bobvanderlinden]

This does seem to be an improvement over what is currently in the manual. The instructions for Linux seem to be correct (which is the part I can currently verify). Seems fine to have this available in the manual already.

[davidak]

@bobvanderlinden thank you very much!

I rebased and built it again. Can we get another review and merge it? I don't want to miss another release.

[thiagokokada]

@davidak Can you fix the two missing . that I found before? Otherwise LGTM.

[davidak]

@thiagokokada i don't think a list of bullet points need a period, but i can do it for consistency. some have them when there are multiple sentences

[thiagokokada]

@thiagokokada i don't think a list of bullet points need a period, but i can do it for consistency. some have them when there are multiple sentences

Yeah, I was saying this mostly because only the first point on each was missing periods.

But I already fixed anyway, going to merge once I got back home.

[davidak]

@thiagokokada sorry i did not get your point why that is useful.

I squashed your commit and added you to co-authors. I like that this is such a collaborative effort with 6 authors!

I also built it again, successfully.

[thiagokokada]

@thiagokokada sorry i did not get your point why that is useful.

I squashed your commit and added you to co-authors. I like that this is such a collaborative effort with 6 authors!

I also built it again, successfully.

I meant, the problem for me was the inconsistency, not correctness. It was only the first point on two different sections that were missing periods, while the other points in the same section included them.

You could either remove all of them or add the periods in the two places that I indicated, that was it.

[thiagokokada]

Let's merge this before 22.11 release cut, so folks have time to improve on it until the release is finished.

[thiagokokada]

Thanks @davidak and everyone else for the improvements.

[github-actions]

Backport failed for release-22.05, because it was unable to cherry-pick the commit(s).

Please cherry-pick the changes locally.

git fetch origin release-22.05
git worktree add -d .worktree/backport-175128-to-release-22.05 origin/release-22.05
cd .worktree/backport-175128-to-release-22.05
git checkout -b backport-175128-to-release-22.05
ancref=$(git merge-base b3c0c4979e3405f3b267e9fd1c81c4f82d8ba44d f701bd59860f4ea75ab0c20095fc8739b487875c)
git cherry-pick -x $ancref..f701bd59860f4ea75ab0c20095fc8739b487875c

[github-actions]

Backport failed for release-22.05, because it was unable to cherry-pick the commit(s).

Please cherry-pick the changes locally.

git fetch origin release-22.05
git worktree add -d .worktree/backport-175128-to-release-22.05 origin/release-22.05
cd .worktree/backport-175128-to-release-22.05
git checkout -b backport-175128-to-release-22.05
ancref=$(git merge-base b3c0c4979e3405f3b267e9fd1c81c4f82d8ba44d f701bd59860f4ea75ab0c20095fc8739b487875c)
git cherry-pick -x $ancref..f701bd59860f4ea75ab0c20095fc8739b487875c