Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve errors page #1299

Closed
dichotommy opened this issue Nov 22, 2021 · 8 comments
Closed

Improve errors page #1299

dichotommy opened this issue Nov 22, 2021 · 8 comments
Assignees

Comments

@dichotommy
Copy link
Contributor

Our current errors page (errors.yaml) is lacking in a couple ways.

Problems:

  • The build-time content fetching from a .yaml file does not add any value
  • Using a .yaml file makes it difficult to integrate w/ VuePress
    • no sidebar
    • no place in the sitemap
    • treated as an external page—.md links do not work
  • Using a .yaml file 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 ).

@dichotommy dichotommy added the P2 label Nov 22, 2021
@guimachiavelli
Copy link
Member

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.

@bidoubiwa
Copy link
Contributor

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

@maryamsulemani97
Copy link
Contributor

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

@maryamsulemani97
Copy link
Contributor

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

bors bot added a commit that referenced this issue Jan 24, 2022
1378: Move errors page from yaml to md file under `reference/api` r=guimachiavelli a=guimachiavelli

As part of our ongoing site restructure, I am moving the errors list from `reference/features` to `reference/api`, turning the `yaml` file into markdown as discussed on #1299.

Co-authored-by: gui machiavelli <hey@guimachiavelli.com>
Co-authored-by: gui machiavelli <gui@meilisearch.com>
@dichotommy
Copy link
Contributor Author

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

@dichotommy
Copy link
Contributor Author

dichotommy commented Feb 2, 2022

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.

@maryamsulemani97
Copy link
Contributor

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

@dichotommy
Copy link
Contributor Author

Completed ✅

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants