Contributing guide as a page

[Chrissdroid]

Making the guide for contributing to docs available as a page (ex: /en/contributing or /en/guide/contributing), can address these issues:

• Allow translation into each language supported
• Allow translators to specify one or more detail about their opinion on the translation on this page (like a link to their glossary page, see #474)
• Allow direct link to this guide for easier sharing when someone want's to be part of the process

• [x] I am willing to make a PR

Open to suggestions, as always !

[sarah11918]

I like this!

Would you suggest still having the i18n guide (Admittedly, I always have to hunt for this myself.) 😅 Would these pages be linked from there? Or do we consider making the main docs README bigger and include more?

There's still an advantage to having one central page, like the one we have now, so that we can have one place where we create it in English, and one place for us to maintain the "one true copy." Then, each language can have its own translated page, resources etc.

[Chrissdroid]

I was wandering this being both a guide for user willing to contribute to the translation as the "i18n guide" but translated to each language to break the language barrier (which can be a problem for some people ) and a guide for contributing to the docs itself

With every language choosing to add one or more section about their methods for translating

[sarah11918]

OK, so the suggestion is we make it as an English "page" (to replace the i18n .md README?) and then it fits into our existing workflow re: when the content needs updating in other languages?

How do we handle each language having some of their own, different content? Do we just use @hippotastic 's automation that when there has been an update to the English, each langugage will update their translation for that part. BUT, at the same time, each language page might have MORE, ADDITIONAL content (that does not match the English page)?

[Chrissdroid]

That's the idea, don't know exactly how hippo could make it work but i think it's more appealing for people via a dedicated page than a README on github (and more easy to share if needed to link it from a tweet or a message) and could let each language have their "unique" (at a certain degree) internal workflow enforcing certain writing style matching theirs method

[sarah11918]

+1 from me, I agree! No need to convince me. :)

I just want to make sure I understand what is being proposed, and how it will fit into what we have.

[hippotastic]

Hmm, I'm not sure if I'm happy with the idea of mixing public-facing and (primarily) internal content in one tool.

Just a quick alternative idea: What if we unlock GitHub's wiki feature for the docs repo? This would be a really simple way for translators to collaborate and it's fully searchable, linkable and right next to the translations on GitHub.

[sarah11918]

Great point, @hippotastic . I know that's where React's French glossary/resources are right now. And I also noticed that only /fr/ is using that there right now. @Chrissdroid - can you imagine something like this working?

[Chrissdroid]

Just a quick alternative idea: What if we unlock GitHub's wiki feature for the docs repo?

I actually thought of that with the i18n-fr team but it mean that we need each language to have their "ambassador maintainers" to have the right to edit theses and maintain them

( could be a pain for @sarah11918 or @delucis to edit everytime there's a change to be done, FOR EACH LANGUAGE 🤣 )

[sarah11918]

Hmm... can someone have Wiki editing permissions WITHOUT having merge permissions?

Note: Fred HAD mentioned designating one Language Lead person, so that idea is not that far off.

[hippotastic]

I volunteer as a tribute... for ambassador maintainer of the German translations at least. 😄

[sarah11918]

... and of course, giving one person per language merge permission is ALSO a possibility! (I think?) Didn't mean to say that it wasn't... just asking whether we can split it up that way.

[Chrissdroid]

@sarah11918 the only resource i could find

[sarah11918]

Well that looks promising! I (Sarah, the human) would be absolutely OK with translators (all of you?) having access to edit the Wiki. And we'd need one ambassador to take responsibility for what your crew does. ;)

[delucis]

+1 either for a wiki or (my preference) internal Markdown files in src/i18n/lang/. Don’t think we need to have this is as a public-facing page. Also, if the English i18n guide is not clear enough, we need to a) make it clearer! but also b) if your English is not good enough for the docs we have, maybe it’s also not good enough to be able to translate? I’m totally in favour of language-specific files like a glossary, but I think it might be better to keep common guidance like the i18n guide centralised?

[Chrissdroid]

if your English is not good enough for the docs we have, maybe it’s also not good enough to be able to translate?

For "review only" i don't think it's a real issue, but yeah, for translation it's a problem

[sarah11918]

but also b) if your English is not good enough for the docs we have, maybe it’s also not good enough to be able to translate?

I had also had this thought.

I (human) don't mind giving access to the Wiki if it's more collaborative, and the ENTIRE team can participate. An internal Markdown file could still only be changed by someone with merge access, right? So, for "official" stuff that's fine. But if a language is wanting a place where anyone can drop in a resource or something, maybe the Wiki can facilitate that a little easier? And keep /pulls a little less overwhelming?

[hippotastic]

One thing that I'd definitely love to see in a wiki is a language-specific translation dictionary that contains translations for common terms from the English pages.

I've made notes already while translating the first German pages and would love to have those in an easy-to-find location where all translators can quickly add new terms without having to go through a PR first.

[Chrissdroid]

@hippotastic that's what we're working on currently with the french team (and why i created the glossary issue)

(At least for the french's docs)

[delucis]

Seems like Wikis and Markdown files would have the same access restrictions: we would need the “language ambassador” to edit the wiki or manage PRs. There don’t seem to be fine-grained wiki-only permissions, so the ambassador would have full merge powers but (given this may be important for the project governance), it would be possible for ambassadors to only have that permission on withastro/docs and not other repos like maintainers have.

Given that, PRs + a Markdown file may even be preferable because it’s a path for non-ambassadors to propose changes without needing to post them in Discord for the ambassador to copy over.

The only other option seems to be to open up the Wiki to literally anyone making changes, which might be OK? But also, this is the internet…

[Chrissdroid]

The only other option seems to be to open up the Wiki to literally anyone making changes, which might be OK? But also, this is the internet…

A wise man once said "Never trust users"

[hippotastic]

I was an active editor and reviewer on Wikipedia for some years and didn't encounter many issues with allowing everybody to edit pages. I think we could give it a go and lock down in case too frequent issues arise.

[delucis]

I think we'd need the other maintainers or Fred as steward to agree to making it open but we could try. If we did, I'd want to have ambassadors in place first so they had moderation powers over wiki contributors.

[sarah11918]

I think my preference is for a solution that does NOT give a language ambassador merge permissions?

It's NOT that I don't trust you all (and, it would likely be those of you in this thread!) It just opens up more safety/security risks for our public-facing docs site, you know? It's more people who can have their GitHub accounts hacked... all kinds of things like that.

And yes, you're right @delucis that at least with PRs, anyone can easily work on/propose changes and share them.

So, @Chrissdroid , what limitations would you have working in the Markdown file system that we can still try to address or make better?

[Chrissdroid]

I don't have any limitations in my mind other than security and permissions issues. The wiki is totally fine to use !

[sarah11918]

I'm looking at that link re: wiki permissions, and we can at least restrict access to "collaborators only." Forgive me for not knowing, is that the same as "Contributors" that are listed on the repository?

(I'm not sure where we're landing on Wiki at all, though! lol.)

[hippotastic]

Unfortunately, on GitHub, "collaborators" are those with write access to the repo. So either you just allow everyone to edit the wiki (which I think will be just fine!), or you need to give everyone who should be able to edit the wiki write access. And yes, that includes merge powers.

[sarah11918]

Aww... Wouldn't a "contributors" option make a TON of sense?? Booooo.

[hippotastic]

Absolutely! For some reason they just didn't implement that yet. 😅