Docs 2

[datdenkikniet]

Working on the migration guide and other docs

TODO:

• Migration guide
• Hardcoded examples should link to example code that is tested (this was already done, AFAICT)
• Address [Book] Improve channel docs for hardware tasks #699
• Discuss: should we remove references to non-v2, apart from the migration guide and link to the book for v1? (Off-github conclusion: yes)
• RTIC {vs,and} Embassy (important: distinction between embassy runtime & HALs)
• More descriptive docs on how to implement & PR implementations of Monotonic to rtic-monotonics

[korken89]

bors merge

[bors]

Build succeeded!

The publicly hosted instance of bors-ng is deprecated and will go away soon.

If you want to self-host your own instance, instructions are here.
For more help, visit the forum.

If you want to switch to GitHub's built-in merge queue, visit their help page.

• ci

[burrbull]

@datdenkikniet What you think about similar PR for this repo rust-embedded/book#356 ?

[datdenkikniet]

I think that it's a nice idea, but also that the amount of overhead it adds to writing docs is not worth it at this stage.

• Just writing the English docs will take more effort.
  • We add a hefty layer of indirection.
  • As is, there are few contributors willing to write/capable of writing docs, making it more difficult is not likely to improve that.
• Whenever we do an update to the docs, we need to poke whoever is maintaining the other language(s)
  • What do we do if the person responsible for maintaining the docs in a different language no longer wants to contribute?

If there is a clearer use-case for docs in different languages that can't be satisfied by using google translate or an AI powered translation service, it would be easier to motivate.

I have no idea how much benefit translations to different languages would actually make, so it's quite difficult to judge for me in that regard. I only know that doing this PR was a chore as-is, and it would've taken a while longer if there were more steps to it.

[mgeisler]

Hey, I saw this linked on rust-embedded/book#356 😄

• As is, there are few contributors willing to write/capable of writing docs, making it more difficult is not likely to improve that.

It's certainly difficult to find people who like to write documentation. In Comprehensive Rust, we've taken the approach to let the translations trail the English documentation: we're adding/removing stuff from the English documentation without regard for the translations — it's up to them to keep up if they want.

The result has been that the Brazilian Portuguese translation is in a rough shape — every time we change a paragraph of text, the translation of that one paragraph falls back to the English text. So it requires a very dedicated team of volunteer translators to keep things up to date.

However, I don't feel it puts additional work on the people who contribute to the source language.

[datdenkikniet]

Thank you for the insight @mgeisler! I seem to have misunderstood and was expecting gettext to error out if it can't translations for a specific sentence. Given that that's not the case, my arguments don't hold as much water :)

Then it's "just" setting up the system and figuring out if we want a threshold for how much un-translated text we're willing to tolerate.

[mgeisler]

Thank you for the insight @mgeisler! I seem to have misunderstood and was expecting gettext to error out if it can't translations for a specific sentence. Given that that's not the case, my arguments don't hold as much water :)

😄 You could still argue that it might look weird for the project to have a set of translations in various stages of decay — that's certainly a concern for me with Comprehensive Rust. It's published by Android/Google, so I ultimately want it to look professional.

Then it's "just" setting up the system and figuring out if we want a threshold for how much un-translated text we're willing to tolerate.

Supporting this would be a matter of "a little scripting". That is, one would need to reuse an old translation if the current translation has degraded too far. I haven't yet written this for my own use, but I've at least recorded the need for this here: google/mdbook-i18n-helpers#16.