Documentation language quality

[0biWanKenobi]

Hello dear community,

I've been using vue-i18n-next for a few months now. It's an essential part of a medium size commercial app that my company is developing, and I'm super happy that localization is so easy thanks to this package. I wanted to preface this discussion like this, so that it is clear I actually appreciate all the work that's been done on this package and how helpful it is.

That being said, I've been really struggling with the official docs. Unfortunately there are many instances where the phrasing is not at all clear, sentences are broken, etc. It is to the point where I can't even contribute a pull request to improve the docs, because I don't understand what is being said in the first place.

I'll post a few examples:

As we have explained, setup in useI18n is a way.

..a way to do what?

---

The above code sets the useI18n option to useScope: 'global'

useI18n is a function, not an option.

which allows useI18n [..]
This allows usei18n [..]

The same sentence is repeated twice, in a very convoluted way, and it's not clear at all what it means.

---

I've just picked a few examples from a page I was scrolling through, but this poor wording can be easily found all throughout the docs. It's gotten me to the point that I couldn't stop from writing this post, and let me be honest: it's not easy for me to do this. I fear it might come through as an attack, a slander, and cause misunderstandings and anger in the community. So let me say this once more: I deeply appreciate this package, the work done by the author and all the contributions from the community. I wouldn't be here writing if it wasn't like that. I'm doing this in hope that it will result in a positive push forward.

So, what can we do as a community?

My personal suggestion is:

• Expert community members, aka people with greater understanding of how this package works, would be the best candidates to submit PRs that can bring the docs to the next level;
• We could have a tag dedicated to this kind of issues. It would help avoiding duplicates, and encourage people to report whenever they find something in the docs;
• Slack / Discord etc could help speeding up the works, maybe

In the end, I hope we can work together for a better package!

Ste

[kazupon]

@0biWanKenobi
Thank you for your suggestions for improvement!
I apologize for providing poor documentation 🙇

I'm vue-i18n creator and creator of the intlify project
However, my native language is Japanese, so my English is not good
(I'm currently learning on improving my English skills by attending an English Scholl)

I'm happy about your suggestion to improve the docs!
And you are the first!

Expert community members, aka people with greater understanding of how this package works, would be the best candidates to submit PRs that can bring the docs to the next level;

Expert community member is a good suggestion! There are several core team members involved in the development of Intlify project, but there is no community member yet to lead the documentation, GitHub issues, and GitHub Discussions.

We could have a tag dedicated to this kind of issues. It would help avoiding duplicates, and encourage people to report whenever they find something in the docs;

Sorry, I was trying to make sense of your suggestion in my head, but couldn't. 😞
Am I right in understanding that we should use some kind of documentation system to report issues from documentation to GitHub issues?

About this issue, I think vue-i18n-next should have a mechanism like Vuepress to allow PR to modify the page at the end of the documentation page using GitHub integration.

The following capture is an image from the official Vue 3 documentation:

Here is the page URL for your reference:
https://v3.vuejs.org/guide/introduction.html#composing-with-components

Slack / Discord etc could help speeding up the works, maybe

We are having discord for members involved in the Intlify project.
We welcome anyone who wants to contribute to the improvement of the docs to join us. :)

[0biWanKenobi]

@kazupon

Thanks a lot for the reply! 🙇

We could have a tag dedicated to this kind of issues.

I was thinking about a tag like the one in the image below, Status: Review Needed. Maybe we could have something like Suggestion: Docs?

---

[...] a mechanism like Vuepress to allow PR to modify the page [...]

I think this would be a GREAT idea! 😎

[...] there is no community member yet to lead the documentation

A dedicated member(s) would be a really good thing, I'm sure it would greatly help and speed things up 👍

Thanks again for replying, I hope vue-i18n-next will continue to improve!