Straight.el: Improve documentation

[titibandit]

I would suggest to organize the documentation differently.
Having everything in this one super massive readme can be really daunting for people not accustomed to straight.el
Then the package appears as being very complex when in reality, much of what's the readme, is not documentation per say. (comparisons with other package manager for example)

I've thought of this when I saw Denis Ogbe here (https://ogbe.net/emacs/emacs.html), detailing his (very interesting!) configuration for emacs.
I quote:
"There are alternatives to the built-in package.el, for example straight.el. It looks like a great project. But the manual is incredibly long, it seems like an incredibly "different" way to handle packages, and I am frankly intimidated by it's apparent complexity."

Which is a shame, since the guy seem clearly able to handle straight.el.

Maybe organize the documentation with several markdown documents? in a wiki?
Just a suggestion that could avoid turning people off because of the appearance the length of the documentation gives to the project.
Cheers!

[progfolio]

Thanks for bringing this to our attention.
I agree we could simplify the README and move some of the other information to a secondary site or document(s). Will discuss with @raxod502

[raxod502]

You aren't the first person to point out this problem. I think you are correct that having multiple sub-pages is better than having one gigantic large page. I think it would be nice to keep the documentation in Markdown format in this repository, although we could certainly make it auto-publish to GitHub Pages for even easier accessibility.

[krdzo]

I will add this here because it doesn't warrant opening a new issue, under the https://github.com/raxod502/straight.el#how-does-straightel-know-what-packages-are-installed section there is a reference to straight-install-package which doesn't exist, just so you know when you reorganize the documentation.
If I find some other issues like this in the documentation I will write them here if that not a problem.

[progfolio]

Thank you for bringing that to our attention. I will fix that ASAP.

If I find some other issues like this in the documentation I will write them here if that not a problem.

I've changed this issue to "Improve Documentation", so please feel free to share anything you find and any ideas you may have about how we could improve the docs.

[4aHxKzD]

I saw a post on reddit regarding this issue, and just wanted to say that the long format of @raxod502's READMEs is one of the reasons why I like to use his packages. Other Emacs packages make me search information all across the web (Github, reddit, EmacsWiki, Blog posts, etc.), but with packages like straight and selectrum I know that all the relevant information is right there in a single file.