User Guide Maintenance

[offset-torque]

ATTENTION PLEASE: This thread carries on from the original user guide discussion thread.

Archived original thread covers the discussions for the PDF version and can be found here: #8058

[offset-torque]

CONTRIBUTING TO THE USER GUIDE

‼️ If you want to make changes to the user guide please read this message carefully.

✅ If you are not changing anything, you can skip this message and write in this thread directly.
Examples: You just have a request or want to report something is missing in the guide.

---

Our user guide is written by a single person (me) with the feedback of devs.
So it is not a collaboratively created document with many authors.
Core principles of this guide are functionality and usability.
Aesthetics comes after these requirements.

If you want to change something in the guide, you should first write in this thread:

• What you want to change
• Why is this an improvement over the current state

Changes that are welcome

• Missing topics: Features of KOReader that you couldn't find in the guide
• Language improvements: Explanation is not clear enough, spelling/grammar mistakes etc.
• Topics that are not directly a feature of KOReader but might help users like the "Optimizing manga for your mobile reader device" section in the guide
• CSS changes that fix some broken behavior with mobile devices or some browsers

Changes that you should be careful about
Any style changes including:

• Font type and properties
• Margins, indents and white spaces
• Colors

Any of the changes proposed in this second group should follow the Web Content Accessibility Guidelines, especially in contrast and readability areas. And you should be able to explain how your change improves the readability, based on design and usability principles. Also if you propose a change to the colors, you should provide a palette which has enough contrast and separation and that is also optimized for color blindness.

Please only suggest a change if you are sure that it will improve the experience of the users reading this guide.
(As an example, you might enjoy "low-contrast pastel colors with tiny fonts" in your text editor, but that is definitely not suitable for this guide.)

⚠️ Any PRs that bypasses this thread will be ignored

[sonix-github]

I would like to contribute to translation of the user guide. Where can I find some kind of template for translation, please?

[Frenzie]

Nothing of the sort exists as of yet, but it should be possible to add it to Weblate.
https://docs.weblate.org/en/latest/formats/html.html

[sonix-github]

Great. I'm looking forward to it :)

[offset-torque]

@sonix-github

I guess that you want to contribute Slovak translation since you added the Slovak keyboard before. I just checked the user guide page translated into Slovak with Google Translate. I looked at random parts and to my surprise they are pretty good (I try to keep sentences short and clear in the English version for our non-English users so that helped maybe). Please have a look yourself. Only possible problem might be menu items in green text.

So what I am saying is, instead of translating all of the guide yourself (which is a substantial effort), you can just proofread a Google translated version which would be much easier.

[Frenzie]

As a quick note on that front, I find that DeepL and perhaps also ChatGPT 3/4 provide a higher quality, more natural translation than Google. But I say that mainly on the basis of Dutch/English/German/French; it might be different for Slovak.

[sonix-github]

@offset-torque: yes, I meant translation to Slovak
No problem for me to translate or proofread machine translation. I regularly contribute to translation of Koreader strings via Weblate

[offset-torque]

Frenzie - I find that DeepL and perhaps also ChatGPT 3/4 provide a higher quality, more natural translation than Google.

It was missing but now I checked again and DeepL added Slovak it seems. Slovak language is generally missing from all translation services/models. Closest thing you can find is Czech language instead, which is very similar to Slovak so they don't bother with a smaller language I guess. GPT3 was prone to hallucinating in Slovak because of sparse training data I think. I haven't checked GPT4 yet.

Maybe we can add some kind of translate widget to the user guide page like some websites do, so users can translate it on the fly to their language.

What do you think Frenzie ? Better than nothing I guess, but I don't know the downsides (Also I don't know how good it is for CJK languages).

[Frenzie]

I'm inclined to think people can enter the link in Google Translate themselves if they want to, but if you want they made it simple to add.