Translation documentation moved to new area.

Translation documentation moved to new area.

от koen roggemans -
Number of replies: 10
Снимка на Language pack maintainers

Hi Moodle translators,

I noticed the documentation for translators and contributors of language packs has moved away from Mediawiki to a new platform: https://moodledev.io/general/development/process/translation

This is part of the move of the whole of the development documentation for reasons I'm not aware of. The translation documentation is a part of this developer documentation and therefore moved too. As I understood, there are no plans to move the user documentation and that would stay at https://docs.moodle.org.

The system used for the development documentation uses markdown files, residing on Github, that are parsed to static HTML files with Docusaurus. The process on how to contribute is on https://github.com/moodle/devdocs. Basically, clone the documentation repository, install some software, make your changes, test by running the software, create a pull request, Wait/hope that it is accepted.

Although I'm familiar with this sort of workflow (I use it for my own blog, using Hugo rather then Docusaurus),  I'm not so happy with this move for a few reasons:

  • Translators are not developers, therefore the process described above might be a daily thing to do for a developer, but not for a translator.
  • Adding useful contributions to the documentation wil therefore happen a lot less then now, because of the longer process.
  • Small corrections in the documentation, updated / improved workflows, bright ideas might not end up in documentation anymore.
  • All credits to contributors for the current documentation are gone.
  • All history of the documentation is gone.
  • All though Moodle translation contributes to the Moodle LMS code, it is not really part of Moodle development.
  • There is no reason, nor benefits for Moodle translators  - just change and added complexity to maintain it.

If I look a the contributions list of the translation documentation, most of the contributions are not done by Moodle developers, but by translators. A lot of work is done by Helen, German, Nicolas, Mary, myself, ... It's community build documentation.

Therefore I would like to create a tracker issue to move the translator documentation back to user documentation (https://docs.moodle.org) or another place where it is easier to maintain by non-developers.

Is there support for my proposal, is there something to add or are translators happy with the move to the new location - also fine? Please comment.

Kind regards

Koen

In reply to koen roggemans

Re: Translation documentation moved to new area.

от Ralf Krause -
Снимка на Language pack maintainers
Hi Koen,
thank you very much for your clear arguments. Yes, the translation for Moodle and its plugins mostly is not done by IT developers. People who want to find hints about the Moodle translation will look into the Moodle docs.
Ralf
In reply to koen roggemans

Re: Translation documentation moved to new area.

от Mitsuhiro Yoshida -
Снимка на Language pack maintainers
Hi Koen,

I totally agree with your idea "Moving the translator documentation back to user documentation (https://docs.moodle.org) or another place where it is easier to maintain by non-developers".

I think it's never a good idea to erase the past history in favor of technology and convenience, so I think we should migrate all the document history along with it, in whatever form it takes.
In reply to koen roggemans

Re: Translation documentation moved to new area.

от koen roggemans -
Снимка на Language pack maintainers
The issue is here: https://tracker.moodle.org/browse/MDLSITE-6728
Please vote if you agree.
In reply to koen roggemans

Re: Translation documentation moved to new area.

от Tim Hunt -

Koen has raised valid pionts, and I don't want to detract from them.

However, I just wanted to point out that for simple edits, there is a much easier process, which can be done entirely within your web browser, and most of the tricky stuff only needs to be done once, the first time.

  1. At the bottom of any docs page (for example https://moodledev.io/general/development/process/translation) click the floating 'Edit this page' link.
  2. (If you don't already have a github login, you will have to create one at this point, but you can do that with just your email address. This is a one-time thing.)
  3. (After that, if you don't already have your own 'fork' of the devdocs repository then you need to create one. I did this over a month ago, so I don't rememer exactly what I did, but I think github guided me. Please can someone do it, and confirm the details. This is also a one-time thing.)
  4. Then you get to an editor in your browser, where you can edit the page.
  5. When you are done, click the 'Propose change' button at the bottom (prefereably providing a brief summary of what the change is.)
  6. Click 'Create pull request' (twice).
In reply to Tim Hunt

Re: Translation documentation moved to new area.

от koen roggemans -
Снимка на Language pack maintainers

Thank you for clarifying this Tim. I looked into the process before making my post.

The complete process is on https://moodledev.io/general/documentation/contributing. Personally I wouldn't dare to try to create a new page.

Please admit that it is more difficult then editing a wiki усмивка, where only step 4 is necessary.

The process doesn't end with step 6: the pull request. Someone whit the gifts of an all knowing God needs to review the request and decide if the information is valid, useful and correct. In a wiki, the next person comes along (or the one who watches that page and is very familiar with the subject) and improves the wording or reverts the nonsense. 

I hope Moodle HQ has thought about the workload for accepting pull requests better then e.g. Nextcloud, where a poll about what people motivate and what slows them down to develop plugins for Nextcloud, the documentation process was marked as one of the problems (See https://help.nextcloud.com/t/improving-nextcloud-documentation-and-community-engagement/142505). A wiki was proposed as solution усмивка, which is what the NextcloudPI developers use, moving away from the core (git based) documentation.

I don't mind change for the better, but I still don't see the benefits of this one, especially not for the translation part. It's a lot of work to do the move, loss of contributors data, processes become more difficult in stead of easier, the process is slower (waiting for pull request approval), more people need to dedicate their time to a change, and so one... anyway, sorry for the rant.