Shrink README to most important items, move documentation/manual.

[ThomasFrans]

Is your feature request related to a problem? Please describe.
I was browsing through the README today to find some information I needed to work on a bugfix and found the current one a bit hard to navigate and a bit overwhelming. I realize the README is the Git repo's entrypoint, the fn main() where new users land and current users expect to find the most important info so I'm a bit scared to suggest changes to it, especially since I think the current one has been the same for a long time.

Describe the solution you'd like
What I would want to suggest is to shrink down the current README to only contain the essential stuff, and provide links to resources that group together related information. The current one has a table of contents but it's a bit long and I think no user would need all the information in there at once. I think therefore it could make sense to split up that info into separate pages/a new documentation format (like mdbook). There could be categories of information, since a user would most likely want to get to information regarding one specific topic as quickly as possible:

• development info
• packaging info
• installation info
• configuration info
• contribution guidelines
• license
• issues
• ....

A user falls into roughly two categories:

• A new user, who wants to get a quick glimpse of what the project is about and how to install it/where to get it. For them it makes sense to offer that info straight in the README as they don't want to have to click around to different pages to get the information.
• A current user/developer, who knows the project and is looking for specific information in one of the aforementioned categories.

Describe alternatives you've considered
I've considered 3 ways to make the current README a bit more clear:

• Create a GitHub wiki page for the items that are currently in the README, but are meant for current users/developers. Keep the project description and installation instructions in the README and mention the wiki for extra information. The disadvantage of this approach is that the project becomes dependent on GitHub, which I personally try to avoid.
• Create separate *.md files that contain information related to a specific topic. Links to them could be provided cleanly in the main README file, and each sub-file could contain its own smaller table of contents.
• Create mdbook documentation for the project. I don't know if this is the best approach as it adds complexity and there isn't that much information that it needs a whole documentation page.

Additional context
If a suggestion would be wanted, I could create a PR to show what I was thinking about. I know the README of a project is very important and I don't want to change it unnecessarily, but I feel like splitting it up could make it easier to quickly get to the relevant information. I could make a PR with a suggestion if it would help 🙂. It would probably roughly put the current top-level items into separate files.

Examples

• Alacritty's README
• Neovim's README (contains a bit more info, but still links to other places regarding extra information)

[hrkfdn]

Solved by #1089