Improve compile-and-run-a-node.md

[ryancwalsh]

I'm on the Engineering team of NEAR Foundation.

I'm trying to follow these steps https://github.com/near/node-docs/blob/211d8e0556c6d6ed90fec15ea38597ff033e170b/docs/validator/compile-and-run-a-node.md

Here are a few problems.

1. I personally would prefer if you'd remove the $ at the beginning of each line so that the commands are easier to copy and paste into the terminal.

brew install cmake protobuf clang llvm awscli
Warning: Treating cmake as a formula. For the cask, use homebrew/cask/cmake
Warning: No available formula with the name "clang". Did you mean cln, cling, clean, vlang, clingo or clac?
==> Searching for similarly named formulae...
These similarly named formulae were found:
clang-format                                   clang-format@8                                 cln                                            clean                                          clingo
clang-format@11                                emacs-clang-complete-async                     cling                                          vlang                                          clac
To install one of them, run (for example):
  brew install clang-format
==> Searching for a previously deleted formula (in the last month)...
Error: No previously deleted formula found.
==> Searching taps on GitHub...
Error: No formulae found in taps.

So I think you might need to remove / replace clang in that MacOS prerequisites section.

3. At https://github.com/near/node-docs/blob/211d8e0556c6d6ed90fec15ea38597ff033e170b/docs/validator/compile-and-run-a-node.md#3-initialize-working-directory-3-initialize-working-directory-2 it should explain what boot-nodes are and why you'd want to specify them during init or not. A later step about config.json is also confusing because it seems to say to delete it (rm ~/.near/config.json) and download a new copy from S3. That's so weird. An explanation would be helpful.

4. See my suggestion at https://discord.com/channels/490367152054992913/542945453533036544/996106206189989909 for improving https://github.com/near/node-docs/blob/211d8e0556c6d6ed90fec15ea38597ff033e170b/docs/validator/compile-and-run-a-node.md#5-get-data-backup-5-get-data-backup-1

5. Typos in https://github.com/near/node-docs/blob/211d8e0556c6d6ed90fec15ea38597ff033e170b/docs/validator/compile-and-run-a-node.md#4-replacing-the-configjson-4-replacing-the-configjson

this field is an empty empty (array?) and "If you had not specify the boot nodes to use during init" should be "If you had not specified the boot nodes to use during init. (change "specify" to "specified" and format init)

I'm doing the massive S3 download now and will see how it goes.

Thanks!

[ryancwalsh]

6. At https://github.com/near/node-docs/blob/211d8e0556c6d6ed90fec15ea38597ff033e170b/docs/validator/compile-and-run-a-node.md#5-get-data-backup-5-get-data-backup it says:

NOTE: The .tar file is around 147GB (and will grow) so make sure you have enough disk space to unpack inside the data folder.

Ideally, there would be a way for me to know ahead of time how large the compressed file download will be and how much disk space I'll need for unzipping too. And since that filesize will grow over time and this documentation will immediately become stale and incorrect, what I'm saying is that there should be a "live" / fresh way for someone to check in the moment to see how much disk space I'll need if I want to run a mainnet node.

Some of us have Macbooks with only a few hundred gigs of available space, and it would be a complete waste of time to find out later that I don't have enough space.

We should put this warning at the top of the docs.

[ryancwalsh]

This has been downloading for 4 hours on a fiber connection and has downloaded 294 GB already, and I have no idea how large it is. I'll probably bail at 350 GB.

[ryancwalsh]

Hey @bucanero ! I hope my comments here are helpful. 😃

By the way, my .near folder is now 319.5 GB and is now doing the final step of downloading more info after the S3 step. So I think my Macbook will literally run out of space and become unusable, but I'm curious to see whether I can get the node running for at least a minute just to experience it.

[bucanero]

hi @ryancwalsh , let me ping @mina86 and @janewang as they can provide you with the best technical answers.

[mina86]

I personally would prefer if you'd remove the $ at the beginning of
each line so that the commands are easier to copy and paste into the
terminal.

Regarding dollar signs, counter argument is that it forces each
command to be executed one-by-one while verifying that no errors
happen. For example, if cloning breaks in `git clone
https://github.com/near/nearcore; cd nearcore; git fetch
origin --tags’ chain the last error on the terminal will be ‘not a git
repository: .git’.

We’re also including command output in a other places in documentation
so there is some value in consistency.

Though in the end I don’t have strong opinions here.

should explain what boot-nodes are and why you'd want to specify
them during init

The mention of boot nodes is unnecessary. Similarly the whole mention
of replacing config.json can be replaced by adding --download-config
flag.

PS. https://near-nodes.io/validator/hardware does say that 500GB is
minimum for running a node.

[ryancwalsh]

@mina86 Thanks for your response!

You have a reason for the dollar signs, and I don't feel strongly either; they're fine.

To clarify my point # 3 about boot-nodes: I don't know what they are, and I imagine most people won't either. The docs currently assume that readers will understand, and I'm just questioning that assumption and suggesting that maybe it's a good opportunity to teach what that means. (People won't know how to make configuration choices if they don't know what they are in the first place.)

About the disk space, yep, I see that it warns about 500 GB minimum. However, I still think what I wrote is true:

Ideally, there would be a way for me to know ahead of time how large the compressed file download will be and how much disk space I'll need for unzipping too. And since that filesize will grow over time and this documentation will immediately become stale and incorrect, what I'm saying is that there should be a "live" / fresh way for someone to check in the moment to see how much disk space I'll need if I want to run a mainnet node.

Thanks.