Update README.

[ThomasFrans]

This is just an example of the change I proposed in #1061. I'm not an artist and my creative skills are about as good as a toddler (maybe even worse). This is just an attempt to show what I meant by shrinking the main README and providing information for users, developers and packagers separately. Therefore the 'subpages' aren't finished yet. I wanted to focus on the main README and ask input first.

Some things I tried to do:

• Increase the size of the screenshot and put it closer to the start.
• Divide the main README into categories based on each type of user, so a user can quickly find installation and configuration info, a developer can find build instructions and a package maintainer can find packaging info.
• Put the most important information for users at the top of the README.
• Remove the long table of contents in favor of a shorter README.

[hrkfdn]

Good call, the README has become quite cluttered. Some comments:

• The main page is very clean, love it!
• The packaging statistics image is quite large, but I think it goes well with the installation instructions. As a user of a specific distro it may be helpful to know it's in the package repositories
• Maybe the building and packaging docs can be merged as they accompany each other quite well. Or do you think that would blow it up too much again?

[ThomasFrans]

The main page is very clean, love it!

I'll be honest, I got the idea for the top section from browsing to other GitHub pages. I really liked the way the Helix README looked, so I got (a lot of) inspiration from their README. One problem with this README is that the icon doesn't show on the GitHub app, as there seems to be a bit of a problem there with parsing the HTML for switching out the icons. It just shows the alt text. A solution could be to use a gray-ish color for the text and not to use the switching behavior for light/dark.

The packaging statistics image is quite large, but I think it goes well with the installation instructions. As a user of a specific distro it may be helpful to know it's in the package repositories

I didn't think about that. I thought it would be good for packagers to know which platforms already have a package available, but indeed it also makes a lot of sense in the installation instructions. Like I mentioned I didn't spend much time on the subcategories yet so there is still a bit of work left there (reordering things, moving/copying things between them...).

Maybe the building and packaging docs can be merged as they accompany each other quite well. Or do you think that would blow it up too much again?

I split them because linking to another file on GitHub doesn't take sections into account (developers.md#section), that only works for the page you're currently on. So for a packager, they would click 'more info' in the main README and it would take them to the top of developers.md, not to the packaging section. I think it makes sense that they also just need the build instructions and the extra packaging info so it might be ok to include it and just have them land on the build instructions first. Another option would be to explain the process of building (in general, no details) and packaging in the packaging file, and link to the detailed instructions from there, although that's yet another link to somewhere else, and too much clicking to get everywhere also becomes annoying. I'll play around with it for a bit 🙂

[ThomasFrans]

I added the package information to the user installation instructions and also did some other small changes to make sure everything is up to date and correct. Most of the configuration section is just copied over to doc/users.md for now as I think it makes sense to provide a file with the default options for that in the future, and shrink the section in the README a bit further.

Regarding the packaging section, I considered adding it to the doc/developers.md file but I think they really don't fit together as they are giving information about two completely different things. The developer page gives development information and gives commands to create development builds, while the packaging page gives instructions on how to compile a release build. I feel like it really makes sense to split them as not every packager might necessarily be a developer. That's why I included specific build instructions for the packaging page and provided a link to the developer instructions in case more information is absolutely required.

The version of the packaging page should now give all/only the commands required to build a package, while the development page provides all/only the information to develop ncspot. If this approach isn't ok, I'll happily move the packaging stuff over to the development page 🙂

[hrkfdn]

Merged! The reason I thought they could go together is because for instance the feature flags may be relevant for packagers, but since there is a link that also works.

Thanks a lot for cleaning up the docs!

[jonathannerat]

@ThomasFrans sorry for the bump, do you remember what font is used in the main screenshot? I couldn't find it in the README nor here.

Edit: I was just skimming through nerd-fonts and looks like Iosevka, but not 100% sure

[ThomasFrans]

@jonathannerat I don't know what font it is. I just copied the screenshot when changing the README as I didn't want to change the actual content too much.