Documentation Update

[TimotiusAnrez]

So I have just use faker again today, and found out that person module has been change to name. Might want to change the docs a bit to help others save a bit of time while creating their faker app.

[ST-DDT]

Which version of faker are you referring to?
Where did you look for the documentation?
Have you seen this page? https://next.fakerjs.dev/guide/upgrading.html#deprecations-and-other-changes
Do you have a suggestion on how to improve the documentation?

[TimotiusAnrez]

I have seen the documentation, and it is already updated to the latest version. But the one in readme.md in the repo still has the old version I think

here is the image.

I know this is not a big deal, and if people look for the real documentation it will show the right modules to use. But for beginner or for others that just rely on the repo readme.md will be confuse.

Although it is just a minor changes, but it will give a better experience

[ST-DDT]

I think you are mistaken here (person is the new module name).

The readme on the default branch (next) shows the content of the next version v8.0.0 that you can test as an alpha already. We explicitly added a version box at the top that allows you to choose which version you want to read.

I dont know any way to make this more obvious.
Do you have a suggestion?

If you visit the npm page then it also shows the correct version: https://www.npmjs.com/package/@faker-js/faker

[matthewmayer]

I think the problem is that if someone skims the documentation, then they will

1. npm install @faker-js/faker (which doesn't install alpha versions, so they get 7.6.0)
2. look for the first example in the README, which refers to faker 8.0.0, so they use faker.person.* instead of faker.name.*

Because our major versions only come every few months, and Github defaults to showing the "next" branch, you have this potential period of a few months where README is ahead of the code.

The section at the top of the README is helpful, BUT when i read READMEs, I generally just skim and look at the code examples.

I think the best solution might be to either
a) dramatically shorten the README, not include any code examples, and just link to the current and next versions of the proper documentation.
or
b) add comments to the code examples in README like //requires Faker 8.0.0 alpha version, prior to Faker 8.0.0 use faker.name.fullName() etc

Bear in mind for every person who gets confused like this like the OP and raise an issue, there are probably 100 people who get confused by this and give up!

[matthewmayer]

we will run into similar issues when #1735 lands - the code in the README for picking locales won't work with the version most people end up installing,

[TimotiusAnrez]

wow.. I didn't know that this issue become more serious that I thought 🥲

[ST-DDT]

Maybe, if we add a little warning indicator there?

(Not sure about the warning text)

[TimotiusAnrez]

that could work, from user point of view (me, to be honest). I tend to skim readme to get to the information that I need like @matthewmayer described. Having a warning that can tell me that you need to look at the docs to use it according to the version that I install definitely help.

[ST-DDT]

I created #1886 to address this issue. If you think we need to add the hint to more places, please let us know.

[TimotiusAnrez]

sure thing

[xDivisionByZerox]

Team decision

We should provide a PR that shortens the README by removing all unnecessary code examples.