meilisearch
Improve errors page
Our current errors page (errors.yaml) is lacking in a couple ways.
Problems:
- The build-time content fetching from a
.yamlfile does not add any value- These error descriptions are not repeated or used on any other pages besides the generated https://docs.meilisearch.com/errors/
- Using a
.yamlfile makes it difficult to integrate w/ VuePress- no sidebar
- no place in the sitemap
- treated as an external page—
.mdlinks do not work
- Using a
.yamlfile for this one page is inconsistent with our other site practices, and makes site maintenance less clear for external contributors and new team members - It is not immediately clear to users or maintainers what is the content of this page, or what are its goals
- Current content is a mix of a) error descriptions copy + pasted directly as they appear from the MeiliSearch error handler, and b) summarized error descriptions w/ tips for resolving them and links to places in the docs that can be helpful
Solutions:
- Make this a regular MarkDown page
- Clarify purpose and expectations of this page
- Add an introduction stating up front what content is available on this page
- Attempt to enforce a consistent format for each error, e.g. "Error message", "Why does this error happen", "How to resolve it", "Example"
This is not our highest priority, but it should be done within the next six months—ideally before or during the migration to Docusaurus (#932 ).
As far as I could trace it, the decision to use a .yaml file for errors was tied to an idea of programmatically connecting errors.yaml on the docs repo with the core repo. The intended nature of this connection is unclear and the people I consulted didn't know much more than that. My guess is that it would have taken the shape of a page listing all errors on the core repo. Or perhaps the other way around so we would write the error messages and core would fetch those so they showed up on e.g. the CLI? 🤷
Anyway, it's obvious nothing/little was ever done, but before we scrap errors.yaml altogether it might make sense to check it one last time others are ok with this change.
Other than that, I agree with everything written above.
The build-time content fetching from a .yaml file does not add any value
Absolutely !
The intended nature of this connection is unclear and the people I consulted didn't know much more than that.
I remember the discussion and yes it was supposed to be linked somehow with the core repo so that they could update it more easily but it did not end up with a viable process.
I agree with you @dichotommy it would be better to have it on a md page. It would also be less of a pain for the scrapping
I like Mailchimp's error page. We currently have most of this information but it's on different pages (FAQ, API README). It would be nice if we could move all of this to one page
Can we make Errors a separate heading instead of having it under API references? We could have two pages here, one with just a general introduction and a table with the different types of errors And the next page could have the list of errors
Can we make Errors a separate heading instead of having it under API references? We could have two pages here, one with just a general introduction and a table with the different types of errors And the next page could have the list of errors
I would support this change 👍🏻
This issue was partially solved by #1378 — a PR which replaced errors.yaml with an easier to maintain .md file. However, the content on the page is still weak. In particular, this part of the issue is still relevant:
Attempt to enforce a consistent format for each error, e.g. "Error message", "Why does this error happen", "How to resolve it", "Example"
In addition, #1378 did not completely remove the file responsible for converting errors.yaml into javascript: .vuepress/error-pages/index.js. This remains to be done.
Attempt to enforce a consistent format for each error, e.g. "Error message", "Why does this error happen", "How to resolve it", "Example"
I think we can cover this part in API references if we decide to go with the failure tabs with each example