[Docs] Revamp the docs

[MuhammadM1998]

Describe the feature

Hello,

I think the docs lack some important information and often lead to confusion (which happens with me and with others as I see on Discord). For example, #2546, Discord question about fallback locale. Also, the current docs site is using docus which is currently abandoned & unmaintained.

I'm suggesting reworking the docs (maybe in Vitepress, Nuxt Content & Nuxt UI Pro if available). Also, provide entry points (a place to start from) to onboard whoever wants to contribute to the docs.

I'm willing to do the reworking & contributing to the docs if guided correctly

Additional information

• Would you be willing to help implement this feature?
• Could this feature be implemented as a module?

Final checks

• Read the contribution guide (The contribution guideline of nuxt-modules/i18n is compliant with Nuxt too).
• Check existing discussions and issues.

[BobbieGoede]

You're right, most of the questions asked in the Discord channel are caused by lack of documentation, we should definitely improve the docs!

I'm willing to do the reworking & contributing to the docs if guided correctly

That would be very helpful! I think the description here https://github.com/nuxt-modules/i18n/blob/main/CONTRIBUTING.md#documentation isn't quite up to date (docs:setup script doesn't exist), but expanding on the docs should be relatively straightforward by following the structure of existing pages. If you have any questions let me know!

I think the priority for the docs right now would be adding any missing information and clearing up material that can cause confusion, ideally keeping PRs on a per topic basis to make the process of reviewing and merging quick and easy. Replacing Docus would be nice, but I would consider it a lower priority.

[MuhammadM1998]

Thanks! I've suggested the replacement of docus as I think adding to the docs requires digging into the module and trying out different things which I think will take a huge time and should be in chunks by different people who hit something and then let other people know about and so on.

I'd appreciate if you share the basic steps I'd need to do. For example If there's a source I can get the information from and organize it in the docs (code JSDocs, original vue i18n docs, etc)

[BobbieGoede]

Honestly, you're right that adding or updating the docs requires a good understanding of the way the module works, and there isn't really a good source of information other than going through the code.

As I don't contribute to many projects besides this module, I likely have the most up to date understanding of its inner working and where they meet vue-i18n. For me the most difficult part is knowing which topics need rewriting or improvement, we could try and make a list based on the questions on discord, in issues and in discussions, using that I can try and clarify those in the docs.

I think it would be unreasonable to ask you or anyone else to go through the code just to improve/update the docs 😅

[MuhammadM1998]

You're right for sure. That's way I suggested working on migrating to Vitepress as this doesn't require understanding how the module works and I want to contribute to this project.

I'm down to dig deep into the module but honestly I don't think my current level with TS and how modules work is enough so I'll waste a ton of time going back and forth. Also as you said you can't blame anyone who doesn't want to understand how the module fully works to update the docs.

Opening an issue/discussion with a checklist of all points would be a great start IMO. People then can skim these points and say if they want to contribute to it then gets assigned. Something like this (Screenshot from biomejs/biome#1380)

I've personally asked many questions (Mostly answered by you, thanks a lot btw 😂) and would ask you to assign me the corresponding points in that future issue.

The last thing Is Docus really feels out of date and as of now the docs seem to need time to be updated, I'd suggest reconsidering revamping the docs site. Sorry if I seem insisting 😅

[BobbieGoede]

The last thing Is Docus really feels out of date and as of now the docs seem to need time to be updated, I'd suggest reconsidering revamping the docs site. Sorry if I seem insisting 😅

While I do prefer the look and feel of documentation websites made with Vitepress in general, I'm not sure how Docus feels dated in comparison, they're quite similar really.

But besides our personal opinions about it, since Docus is no longer maintained it's good to consider alternatives, whether that be Vitepress (my preference) or something like Nuxt Content, I'd like to hear @kazupon's opinion on this first 😄.

Opening an issue/discussion with a checklist of all points would be a great start IMO. People then can skim these points and say if they want to contribute to it then gets assigned.

Will probably set up an issue to track this sometime soon, if you already have some ideas to improve some of the docs based on the questions in Discord, feel free to open PRs to do so!

[MuhammadM1998]

Makes sense! let's wait for kazupon's opinion. I'll add to my list revisiting Discord and see if I could open a PR 🙏

[kazupon]

Nuxt i18n is the nuxt ecosystem.
So We should use the docs that nuxt uses.
Of course I know that vitepress is also a great docs site builder! :)

The reason nuxt i18n uses docus is simply that I was using the docs of other nuxt modules as they are.
I see nuxt tailwind and nuxt image don't seem to use docus now.

I think nuxt i18n docs should also be migrated to the new docs with that as a reference.

[MuhammadM1998]

Nuxt, Nuxt Image, Nuxt Tailwind, Nuxt UI and others modules uses Nuxt content and Nuxt UI Pro.
I could work on this locally (Nuxt UI pro is free in local dev env). Then publish it when a license is available.
If that's ok please assign me this and I'll start working on it 🙏

[kazupon]

@MuhammadM1998
You can start it! :)
If you want to use Nuxt UI Pro, I think we can talk to the Nuxt UI team. /ping @atinux

[MuhammadM1998]

Thanks! I'll get started on it