Improve project documentation and update error card

[PencilNavigator]

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

if the above solution is too hard for the maintainers to do, then just change 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.

[PencilNavigator]

@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 😅.

[PencilNavigator]

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.

[PencilNavigator]

@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.

[PencilNavigator]

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 👍🏻?

[rickstaa]

I changed this issue to a proposal 👍🏻.

[francois-rozet]

I do agree that shoving all the documentation in a single README is not the greatest approach. Currently, users have to scroll the equivalent of three screens to reach the first example of a stat card.

I think the main README should only demonstrate the main features of the repo and redirect to other sources for more details (settings, themes, API details, etc.). However, I agree with @anuraghazra that we should keep it simple and setting up a full documentation website for the relatively few features we provide is not necessary. IMO, markdown files hosted on the repo are more than enough, and easier to maintain.

Now, for the translation part, I am all for inclusive documentation, but I think it is a huge burden for the maintainers and actually a disservice for users. Currently, most if not all translated READMEs are severely out-of-date, meaning that users that go to the French or Chinese READMEs get wrong information. And let's be honest, 99.9999% of people that use or could be interested in using GitHub Readme Stats, that is developers, can read English.

Finally, it is not necessary to hard code table of contents in READMEs anymore. GitHub added an automatic TOC button at the top left corner of READMEs a few years ago.

[qwerty541]

@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 👍🏻?

According to my feelings, at this stage of the project's existence, the solution with the creation of a separate site with documentation seems to me unnecessarily complicated. A simpler solution could be, for example, changing the page to which the link https://tiny.one/readme-stats leads to #1772 instead of main repository page. Thus, we will get rid of the problem with a lot of similar issues about public deployment downtime.

I do agree that shoving all the documentation in a single README is not the greatest approach. Currently, users have to scroll the equivalent of three screens to reach the first example of a stat card.

At the same time, I agree with @francois-rozet that the structure of the README.md file could be improved. For example, we could move the rather large https://github.com/anuraghazra/github-readme-stats#all-demos section into a separate file. It would also speed up the loading of the page and reduce the load on public deployment.

Now, for the translation part, I am all for inclusive documentation, but I think it is a huge burden for the maintainers and actually a disservice for users. Currently, most if not all translated READMEs are severely out-of-date, meaning that users that go to the French or Chinese READMEs get wrong information. And let's be honest, 99.9999% of people that use or could be interested in using GitHub Readme Stats, that is developers, can read English.

I like this point of view, I think we should consider dropping support for documentation translations entirely. In any case, no one is engaged in full support for translations. In their current form, they are completely useless and confuse users. The nearest prospect for the development of documentation translations is Crowdin integration, but how is this different from the automatic translation built into Google Chrome? 🤔

I also created pull request #2947 which adds notation about outdated translations. @rickstaa please check it.

Finally, it is not necessary to hard code table of contents in READMEs anymore. GitHub added an automatic TOC button at the top left corner of READMEs a few years ago.

Unfortunately this feature available only on file page https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md, but not on main repository page. I assume that most of users read documentation on main page, so we should keep TOC for now.

[francois-rozet]

Unfortunately this feature available only on file page

It is available on the main page as well, at the top left of the "readme" card.

[PencilNavigator]

A simpler solution could be, for example, changing the page to which the link https://tiny.one/readme-stats leads to #1772 instead of main repository page. Thus, we will get rid of the problem with a lot of similar issues about public deployment downtime.

This was mentioned as an temporary alternative solution above in the "Describe alternatives you've considered" section. Yes, this might solve it for now, but a documentation site is definetly better.

[rickstaa]

First of all, @qwerty541, @francois-rozet, thanks for your input. I agree with most of the things you two mentioned.

According to my feelings, at this stage of the project's existence, the solution with the creation of a separate site with documentation seems to me unnecessarily complicated. A simpler solution could be, for example, changing the page to which the link https://tiny.one/readme-stats leads to #1772 instead of main repository page. Thus, we will get rid of the problem with a lot of similar issues about public deployment downtime.

Let's, as a start, update the card error so that it points to the new COMMON_ERRORS.md suggested by @anuraghazra we can then drop #1772.

At the same time, I agree with @francois-rozet that the structure of the README.md file could be improved. For example, we could move the rather large https://github.com/anuraghazra/github-readme-stats#all-demos section into a separate file. It would also speed up the loading of the page and reduce the load on public deployment.

@mezzode attempted to improve the readme in #2242. Does this suit your need? We can review it again and solve the conflicts.

I like this point of view, I think we should consider dropping support for documentation translations entirely. In any case, no one is engaged in full support for translations. In their current form, they are completely useless and confuse users. The nearest prospect for the development of documentation translations is Crowdin integration, but how is this different from the automatic translation built into Google Chrome? thinking

I agree. I don't like to include these translations if they are outdated. They will leave people confused (e.g. #2959). I would love to eliminate them, but I understand I come from a country where 90% speak English. I think having machine-generated translation is very useful for people in countries where this percentage is still lower (see https://en.wikipedia.org/wiki/List_of_countries_by_English-speaking_population). Maintaining manual translations is undouble for an OS project. If the other collaborators are okay with #2489, I think @anuraghazra can go ahead and perform the steps described by @andrii-bodnar in #2489 (comment).

Unfortunately this feature available only on file page https://github.com/anuraghazra/github-readme-stats/blob/master/readme.md, but not on main repository page. I assume that most of users read documentation on main page, so we should keep TOC for now.

@francois-rozet thanks for making me aware of this feature I did not yet notice it! @qwerty541 I checked and it seems to be available also on the REPO page.

It could be that people like me who didn't notice it yet have a more challenging time navigating the documentation since it is pretty long, but if you want to remove it, feel free to create a pull request 👍🏻.