Cleaning up main REAMDE

[schomatis]

I would like to give more visibility to sections like "Getting Started", "Contributing" and "Want to read our code?". Maybe we could:

• Move the Install section (with many OS/architecture specific details) to its own document in the docs dir and just link to it in the README.

• Remove the Usage which takes up a lot of space and just shows a (possible outdated) help message that the user can easily obtain by typing the ipfs command (which can be hinted in the "Getting Started" section). At the very least it can be moved to its own docs entry.

• Maybe reduce the Docker usage section in favor of enlarging the simpler and more accessible to the user (who may not know how to use Docker) Some things to try section.

[schomatis]

/cc @Mr0grog

[Mr0grog]

Hmmmmm! Initial reactions:

Move the Install section (with many OS/architecture specific details) to its own document in the docs dir and just link to it in the README.

I think installation instructions are really important, so I’m wary of hiding them. But you are totally right that this section is way too big and long, with a huge number of choices and options.

My take:

• Keep the first paragraph about canonical instructions
• Keep the “install prebuild packages” subsection
• Keep only the links at the top of the “from Linux package managers” subsection and redirect those links to either the docs site or to your new doc in the docs directory. Remove the details of each package manager from the README.
• Move the remaining subsections (building and updating) entirely to your new doc in the docs directory and link them from the README.

Remove the Usage

I think “usage” sections are also super important in the README, but they should be more like what the “getting started” section is. You’re right that just printing the output of ipfs --help is pretty redundant.

My take: replace the existing “usage” section with the content of the “getting started” section. Maybe add some more stuff there (or, I guess, to “some things to try”).

Maybe reduce the Docker usage section in favor of enlarging the simpler and more accessible to the user (who may not know how to use Docker) Some things to try section.

100% agree! Just move the docker stuff into a separate doc and link it (maybe from the “install” section) 👍 👍 👍

[Mr0grog]

Also, a thing that is missing from usage/getting started: clearly stating that normal usage is to run ipfs daemon in the background and other commands will interface with the running daemon.

[schomatis]

Cleaning this up would help making excellent documents like #5864 more visible.