[docs] Make it clearer when to use `AdapterDateFns` or `AdapterDateFnsV3`

[mikebski]

Related page

https://mui.com/x/react-date-pickers/adapters-locale/#with-date-fns

Kind of issue

Broken demo

Issue description

In the quickstart, there should be a quick mention of which AdapterDateFns will work with which version. I spent a lot of time getting an import error and the docs on the versions of the adapter are pretty buried, and searching for the answer via google did not give me anything. The error message is not helpful at all. See for details on that: https://stackoverflow.com/questions/79286567/x-date-formatters-missing-lib-format-longformatters-specifier-in-date-fns/79291448#79291448

I was also not able to get the latest version of Moment to work with the Adapter, so I switched to date-fns instead. If that is a version conflict there should be mention of that in the quickstart.

Context

I'm trying to use the quickstart, and almost gave up entirely until I spent hours and hours to find the adapter versioning bit.

Search keywords: AdapterDateFns AdapterDateFnsV3 and Moment support

[michelengelen]

Thanks for pointing that out @mikebski ... I'll add this to the board for the team to pick up! 👍🏼

[flaviendelangle]

On the Getting Started page, the demo showing how to import the adapter explains which one you should use:

It would be awesome to have a better error message, but we don't have the hand on the building phase (which is where it fails since the change before date-fns v2 and v3 is how you import the methods).

We could make the a warning callout in this section just before "LocalizationProvider" for it to be more visible.
Or even a dedicated section (since it's not a problem that will go away soon given the time it will take for people to migrate away from date-fns 2).

Alternatively we could add it to the FAQ, not sure if it's more discoverable or less discoverable than the other section...

[mikebski]

People are going to use a search engine to find the answer when they get the error.

I think in addition to what you're doing, even if you don't have a proper error message, you could include the error message somewhere in your FAQ/docs so it's easily discoverable.

My SO question will probably do that, too, so maybe it's less important now.

[flaviendelangle]

People are going to use a search engine to find the answer when they get the error.

Which would be a good reason to use a dedicated section (either in the FAQ or the getting started page), because those are indexed by our internal search engine.
For Google in both cases the content in in the page so it doesn't change much.

Having the error message would probably help discoverability through Google (or good old Ctrl + F).

[LukasTy]

We decided to add an FAQ section on v7 and v8 docs.
Prioritize indexing (Algolia) for the section heading.