You're welcome! It's definitely a temptation to use the README for documentation, since it is right there and Github displays it nicely for you. But dumping full docs into a README is just going to make it too huge for a new user to easily scan and they will leave disinterested, and it is too difficult to navigate for existing users to easily find what they need.
Github's Wiki is just as easy to use and gives you proper navigation for small, flat documentation needs. For larger and more complex docs, it's probably better to keep your markdown in the project and integrate it with a static site generator1, so that the release of the project also publishes the docs to Github Pages or something like that. Either way, it's better for everyone than putting it in your README.
Orchid is a great choice of SSG for documentation. It can generate full Java or Kotlin API docs along with wikis and blogs and publish it all to Github Pages automatically, and it integrates seamlessly into your Gradle build </shameless-self-promotion>↩
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
You're welcome! It's definitely a temptation to use the README for documentation, since it is right there and Github displays it nicely for you. But dumping full docs into a README is just going to make it too huge for a new user to easily scan and they will leave disinterested, and it is too difficult to navigate for existing users to easily find what they need.
Github's Wiki is just as easy to use and gives you proper navigation for small, flat documentation needs. For larger and more complex docs, it's probably better to keep your markdown in the project and integrate it with a static site generator1, so that the release of the project also publishes the docs to Github Pages or something like that. Either way, it's better for everyone than putting it in your README.
Orchid is a great choice of SSG for documentation. It can generate full Java or Kotlin API docs along with wikis and blogs and publish it all to Github Pages automatically, and it integrates seamlessly into your Gradle build
</shameless-self-promotion>↩