search

nix-community / nixos-install-scripts

collection of one-shot scripts to install NixOS on various server hosters and other hardware. [maintainer=@happysalada]
127 stars 68 forks source link

separate install instructions #2

Closed happysalada closed 3 years ago

happysalada commented 3 years ago

I was thinking of separating the install instructions and detail a little more.

I ran into some of the problems mentioned in the install script and I thought I would make them clearer.

This is just a suggestion, I'm happy to amend.

I was thinking of potentially adding screeshots? and/or removing the instructions from the script directly.

happysalada commented 3 years ago

@nh2 if you feel that PR is not valuable enough, even with screenshots, I don't mind closing it. If you feel it's a matter of adding screeshots, then I can definitely do that.

No worries in both cases!

nh2 commented 3 years ago

Hey, sorry I hadn't had time yet to check it out.

I believe that we should have the instructions in the install script, especially because I expect many users to fork them / put them in a gist which will then be decoupled from the surrounding documentation, and I think that a script that will wipe your disk should carry with it some very clear instructions of what it does and what you need to do to use it well.

The main drawback for me is additional maintenance, especially keeping it up to date when Hetzner changes their UI. However, if you're up for helping maintain it, that drawback is gone. If your goal is to make it as obvious/easy as possible, I think screenshots would be a good idea.

Beyond that, I'd just ask to clear up spelling and make punctuation consistent, and also that the Markdown sublists render cleanly in the generated HTML (e.g. Github preview).

happysalada commented 3 years ago

@nh2 sorry for pushing you, I thought it went through the cracks. No rush at all on this.

How about having both sets of instructions, in the script and in the readme? Maybe it's confusing? I'm definitely not a pro, but it took me some time to get the instructions right. Here is what I went through.

I don't know of anybody else going through the motions, maybe I'm the only one who had problems with it.

The other potential way would be to edit the instructions in the script. I feell it doesn't need to be so detailed in the script, the only time that you need to be accompanied carefully is the first time you go through the procedure.

I think you're right about the screenshots, if it's needed, it will become apparent, and it can be solved then.

nh2 commented 3 years ago

@happysalada :+1: You didn't answer the main question though:

if you're up for helping maintain it, that drawback is gone.

Are you up for helping maintain it?

[fix: markdown](/nix-community/nixos-install-scripts/pull/2/commits/ab1bb524f7b72c67ec75ab4d8867899d03f1d110)

That still isn't working; if you view your change at https://github.com/nix-community/nixos-install-scripts/blob/ab1bb524f7b72c67ec75ab4d8867899d03f1d110/hosters/hetzner-cloud/README.md it shows that:

image

The inner list should be indented; you can achieve that by indenting by 4 in the markdown.

I think you're right about the screenshots, if it's needed, it will become apparent, and it can be solved then.

Sorry, I think you misunderstood me: I think screenshots are great! Especially given the explanations you made of what can go wrong. Do add them :)

happysalada commented 3 years ago

@nh2 thanks for reviewing it again!

I'm interested in maintaining this! (I was a little bit hesitant because I only started nix one month ago, but so far I really love it!)

I'll make a separate PR to add the screeshots. (at the same time I review the baremetal installation probably) Thanks for the feedback!

nh2 commented 3 years ago

OK great!