Improve project documentation and update error card

[pencilnav]

Proposal

It would be nice to have a semi-automatic, easy-to-maintain documentation website. This would provide a clear place for users to find documentation on the GRS tool, leading to fewer duplicate issues.

Added by rickstaa on 15-07-2023

Is your feature request related to a problem? Please describe.

as you see, in the error page card it tells users to make a issue in this github repository. This can be misleading for some users because they just go straight ahead fileing a issue instead of searching all pass issues.

i used the keyword "https://tiny.one/readme-stats" to search, and i found about 15 duplicate issues all because of PAT limit and the error card was shown, telling users to file a issue here.

Describe the solution you'd like

Instead of telling users to file a issue straight, i think we should refer them to a documentation/wiki page that includes most of the common errors and their fixes. Then in that page, mention if non of the above fixes your issue, then go ahead and file a issue.

Describe alternatives you've considered

easy alternative will be just charging https://tiny.one/readme-stats redirect link to readme and change "file an issue" to "check readme.md"

Additional context

N/A

[rickstaa]

@pencilnavigator good idea. You are welcome to create a pull request to improve the behaviour 👍🏻. We now store the common error codes in #1772 in the hope people will check that, but you are welcome to suggest a better place.

[pencilnav]

@pencilnavigator good idea. You are welcome to create a pull request to improve the behaviour 👍🏻. We now store the common error codes in #1772 in the hope people will check that, but you are welcome to suggest a better place.

why not store it in Github wiki? imo storing it in a issue isn't the best idea to do as issues are for reports, not documentation.

[rickstaa]

@pencilnavigator good idea. You are welcome to create a pull request to improve the behaviour 👍🏻. We now store the common error codes in #1772 in the hope people will check that, but you are welcome to suggest a better place.

why not store it in Github wiki? imo storing it in a issue isn't the best idea to do as issues are for reports, not documentation.

That would also be a good place. The Wiki, however, has to be enabled by @anuraghazra if we want to do this. I don't have those permissions 😅.

[pencilnav]

Hi, some updates.
I am currently building a documentation website for GRS with detailed instructions on customizing stats card and common issues solutions. (https://github.com/PencilNavigator/grs-docs)

The current README.md is too crowded with lots of stuff in (which shouldn't because README.md is suppose to be short and only go over briefly), by moving all deep-in customization to docs and only keeping basic information on README.md, users can read through it, then if they want to go deeper, visit the docs website.

The tool i used to build the docs website is mkdocs-material, it's open sourced under MIT and easy to use with many useful functions. You can check out their repo with the link above.

What i'm thinking of is when user experinced an error, the error card gives a link that redirects them to a common issues section on docs website with common error codes and solutions to fix it, then if user still cannot fix, guide them to file an issue on docs website instead of doing that on error card.

I should note that the docs website is still under construction and more are going to be added in the future, but when the website is fully documented, it should look something like this.

[rickstaa]

Hi, some updates. I am currently building a documentation website for GRS with detailed instructions on customizing stats card and common issues solutions. (https://github.com/PencilNavigator/grs-docs)

The current README.md is too crowded with lots of stuff in (which shouldn't because README.md is suppose to be short and only go over briefly), by moving all deep-in customization to docs and only keeping basic information on README.md, users can read through it, then if they want to go deeper, visit the docs website.

The tool i used to build the docs website is mkdocs-material, it's open sourced under MIT and easy to use with many useful functions. You can check out their repo with the link above.

What i'm thinking of is when user experinced an error, the error card gives a link that redirects them to a common issues section on docs website with common error codes and solutions to fix it, then if user still cannot fix, guide them to file an issue on docs website instead of doing that on error card.

I should note that the docs website is still under construction and more are going to be added in the future, but when the website is fully documented, it should look something like this.

Damn, having full-fledged documentation would be amazing 🚀! Feel free to create a Pull request so we can merge it into the upstream and add it under the repository website URL! I think the documentation and #1761 would significantly improve the project.

[anuraghazra]

why not store it in Github wiki?

Let's just put it on Wiki, it will cause issues since external contributes or people outside the team won't be able to contribute to it or change anything.

We can add it in the repo itself inside a different readme, maybe COMMON_ERRORs.md, like we have for the theme catalog.

[pencilnav]

@anuraghazra MKDocs works like Github Wiki, but better. With MKDocs, all documentation is still written in markdown (exactly like wiki). But since it's in a repository, everyone can submit a PR on changes to documentation instead on waiting a collaborater on your side to add it manually.
MKDocs can automatically publish it's site with Github Actions to github pages for every commit (you can use other serverless service to deploy if you want, including vercel). see here.
MkDocs has lots of useful features, it also looks better with the material theme for users.
TBH, i don't mind using wiki because i think this project really needs a documentation to avoid all these invalid & duplicate issues, but i generally think mkdocs (with material theme) is a better documentation thing then traditional wiki.
You can check the one i built here: https://grs.999857.xyz , and just to note, when the documentation is completed, it should look something like this.

[anuraghazra]

Let's just put it on Wiki,

Okay lol I meant to write "Let's NOT put it on Wiki"

We can add it in the repo itself inside a different readme, maybe COMMON_ERRORs.md, like we have for the theme catalog.

[pencilnav]

well, if we have a documentation site, we can display way more things then just common errors.
For example, we can move the crowded readme.md to the docs site, and make it simple for newcomers. (which is one of the benefits i mentioned above) and also for people who want to go deep in, to have a detailed documentation on all the stuff they can do.
I personally think this is better for view. But anyways the decision is on your side. (a common issues things is really needed to avoid all these invalid & duplicate issues)

[rickstaa]

well, if we have a documentation site, we can display way more things then just common errors. For example, we can move the crowded readme.md to the docs site, and make it simple for newcomers. (which is one of the benefits i mentioned above) and also for people who want to go deep in, to have a detailed documentation on all the stuff they can do. I personally think this is better for view. But anyways the decision is on your side. (a common issues things is really needed to avoid all these invalid & duplicate issues)

I agree that documentation libraries like Sphinx, mkdocs and Gitbook are cleaner than a long README. In most of my own repositories, I use sphinx with gh-pages to build docs automatically using a github action, but the other two are also great. The most important thing to consider is to have a system that is easy to maintain. Ideally, something that could work with our new automatic translation provider (see #2489).

[anuraghazra]

Let's start simple. Investing in documentation site is good but also takes effort and time to do so.

As a phase 1, let's try fixing this immediate issue by changing the error card link and adding that COMMON_ERRORS.md file.

We can restructure our /docs folder as such:

• docs
  • translations/*.md
  • COMMON_ERRORS.md

[lostgirljourney]

well, if we have a documentation site, we can display way more things then just common errors. For example, we can move the crowded readme.md to the docs site, and make it simple for newcomers. (which is one of the benefits i mentioned above) and also for people who want to go deep in, to have a detailed documentation on all the stuff they can do. I personally think this is better for view. But anyways the decision is on your side. (a common issues things is really needed to avoid all these invalid & duplicate issues)

I agree that documentation libraries like Sphinx, mkdocs and Gitbook are cleaner than a long README. In most of my own repositories, I use sphinx with gh-pages to build docs automatically using a github action, but the other two are also great. The most important thing to consider is to have a system that is easy to maintain. Ideally, something that could work with our new automatic translation provider (see #2489).

Docusaurus 2.0 can be used for documentation. As per the mention of the automatic translation provider, Docusaurus 2.0 provides the integration.

[rickstaa]

@anuraghazra I agree with @pencilnavigator and @lostgirljourney that simple documentation would benefit the repository. I also know how much time creating and maintaining good documentation can take, so we need a clear plan.

I do think tools like mkdocs and docusaurus can make this easier. Since they rely on markdown, we can spend less time translating the README into a new structure. I prefer these two tools. They both can do the job, but I do think that docusarus its translation feature pairs nicely with the Crowdin integration done by @andrii-bodnar. For Mkdocs, a separate plugin is required (see https://github.com/ultrabug/mkdocs-static-i18n).

@qwerty541, @francois-rozet, @Zo-Bro-23, what are your thoughts on this 👍🏻?