GNOME Bugzilla – Bug 650728
Desktop Help guide -- feedback while translating
Last modified: 2011-09-19 17:03:17 UTC
Here comes various points that I found while translating the doc. It goes from a simple typo to more philosophical matters (joke), including doc structure and mallard bug. There is a bunch of things, so I put them all together to avoid notification flooding, but - If you need separate report for each, or some of them, let me know! - If you want patches, let me know too! It would be great if someone can add a short comment for each entry ========================================================== #: C/index.page:17(title) msgid "" "<media type=\"image\" src=\"figures/yelp-icon-big.png\">Yelp logo</media> Desktop Help" This should not appear in translatable content as such. but just "Yelp logo" and "Desktop Help" ========================================================== <desc>Desktop Help</desc> <title type='link'>Desktop Help</title> <title type='text'>Desktop Help</title> <title><media/> Desktop Help</title> I am unsure which one appears where in the rendered document. I think they should be differentiated, especially to avoid repetitions like: "(More about) Desktop Help - Desktop Help" Also translations may have short/long versions where English as just short. Suggesting: - "Desktop Help" - "A guide for GNOME 3 desktop users" ========================================================== #: C/shell-overview.page:22(title) msgid "Overview of the desktop" Titles does not seem to match content. "Overview of the desktop" seems to be more an index than an overview. On the other hand, "Introduction to gnome" is not really an introduction to GNOME, but seems like a first overview of the GNOME desktop. I would suggest: - Overview of the desktop - Start applications - Windows and worksp... - Log out ... - Using the desktop (*) (*) right now I use the translation "Tout sur le bureau", meaning "Everything on the desktop". I think it could also be something like "desktop tools", since it is about managing the common desktop items like the message tray, the trash bin, the applications dash, files in general, etc. open to discussion! ========================================================== About <comment> tag content, should this be translated at all? I don't see it on the generated doc. I understand it has hidden authoring comment (right?) ========================================================== Mallard make fail touching one .po triggers regeneration of all pages for all languages = ~30 seconds per language make fails on its essential feature: rebuilding only what needs to be. ========================================================== Mallard make because of the single .po(t) for large document means regenerate all pages after the slightest change, which is long for large documents. Maybe a large document could be cut into several .po(t) files? ========================================================== shouldn't <desc> messages end without a full stop? ========================================================== at [1] for example, make better visual for keys by using <kbd> HTML tag and some CSS See for example [2] [1] http://library.gnome.org/users/gnome-help/3.0/shell-keyboard-shortcuts.html.en [2] http://selfcoded.com/app/justnotes ========================================================== #: C/shell-windows-switching.page:11(desc) msgid "Press <keyseq><key>Alt</key><key>Tab</key></keyseq>." msgstr "" while straight to the point, this is quite poor <desc>ription, possibly meaningless for beginners. ========================================================== #: C/files.page:27(title) msgid "Files, folders & search" suggesting: "files and folders operations" or "files and folders management" the <desc> brings more details ========================================================== #: C/files.page:18(desc) msgid "" "<link xref=\"files-search\">Searching</link>, <link xref=\"files-delete\">deleted files</link>, ^^^^^^^ typo: delete files ^^^^^^ ========================================================== #: C/shell-apps-open.page:10(desc) msgid "Launch apps from the the activities overview." ^^^^^^^ typo: the the ========================================================== Should we need a xref for "hot corner", as we have for "window key" ? ========================================================== Return to main topic I mentioned it somewhere else, I think the "More about" does not work properly, or at least is not used properly. Some pages are index pages in opposition to topic pages. "Further Reading More About Desktop Help — Desktop Help " this makes no sense. The user will NOT find more information about the current topic at this linked page. Suggestion: should it be "return to the main topic" ? ========================================================== .gitignore use /gnome-help/??*/*.page /gnome-help/??*/legal.xml /gnome-help/??*/figures/ instead of one per language ========================================================== in "Thank you for taking the time to read the _Desktop_Help_Guide_." This is not coherent with the actual document title: "Desktop Help" Suggesting: "_Desktop_Help_ guide" ========================================================== in "We sincerely hope that you will never have to use it" just do it! I understand the kind attention, though I would remove the sentence, invoquing "why put a warning when you can undo". I think we should feel no shame. It is a fact that, at this point, people need help. Let's keep the document positive: "glad we helped, enjoy your desktop", or just remove the sentence ========================================================== in "guide tips" and "get involved" More about: "Get more help — Can't find your answer? Found a problem? Tips on using this guide..." bug: "Tips on using this guide" links on this very same page! frustrating bug: Same thing with "Found a problem", links to the same page ========================================================== Overall, about "More about" section I think one need to review the use of "More about". It is sometimes misused or useless, often frustrating. I understand it is generated somehow automatically, but I found too many place where it is very ackward. A better goal and usage description for this section could certainly avoid many ackwardness. Suggesting: 1. clarify the goal, use and place in generated document 2. put no links, unless they are truly useful 3. add a "Back to main topic", when linking to an index-like page. ========================================================== "Get more help" This title is misleading. There is NO more help in this section, at most by using the guide better... but if the user read it all, there is NO MORE here. The description has a "Can't find your answer?" but it leads nowhere. Overall it is about - how to use the guide - how report errors ==> Suggesting: "Get better help" "Tips on using this guide" Open question: Isn't mallard completely failling his mission if this section is needed !? ==> Suggestion: make it just work and remove the topic "Found a problem?" This is also misleading, the user *has* his own problem, but this section is about problem with the help system and about reporting error or missing info in the doc. ==> Suggesting: "Reporting error or missing help topic" or "Participate to improve this guide" But better, I would suggest to add a topic describing how to really "Get more help", including: - which irc channels, and how to do (links to irc/IM) - which mailing list, and how to do (links to email) - which user forum So it would become: ==> Suggesting: "Get better help Can't find your answer? --> link to new topic Participate to improve this guide --> as it is Tips on using this guide --> as it is IF NEEDED AT ALL ========================================================== in http://library.gnome.org/users/gnome-help/3.0/get-involved.html.en The title is "Noticed a problem with the help?", but the content is "Get involved to improve the content" this is not clearly coherent. see also above, suggesting better topic title. ==> Suggesting: add a first paragraph like: "This help system is created by volunteer community, participate, report errors, translate into your language, add missing topics..." ========================================================== #: C/web.page:15(desc) msgid "" "<link xref=\"web#connections\">Internet connections</link>, <link xref=\"web#chat\">starting chats</link>, <link xref=\"web#email\">email accounts</link>, <link xref=\"web#browser\">plug-ins</link>..." we have such string in many places. This is an open question: I think it should be split for translation. Although not all languages compose sentences with ",", Unless it is considered as a bullet list. Related to this, each <link> entry has a <title> counterpart, shall the text be identical or differentiated? If <desc> remains as it is, and title should be identical, it would be good to have a TRANSLATOR comment that they should be identical. ========================================================== <link xref=\"web#browser\">plug-ins</link>..." Suggesting: "web plug-ins" ========================================================== "<link xref=\"media#music\">iPods</link>, \n" I saw later that the topic is full of "iPod", should we use a more generic term? or did iPod became a generic enough? ========================================================== <info><title> vs <title>, how they are supposed to be different? Where do they appear in the generated document? in .po files, we cannot differentiate them, both appear as <title>. It would require to check all <title> in the source code, because there is no other way to know if a title has a specific role/type. For Example: --------------------------------------------- .po #: C/net.page:46(title) msgid "Wired" #: C/net.page:48(title) msgid "Wired connections" --------------------------------------------- .page <section id="wired" style="2column"> <info> <title type="link" role="trail">Wired</title> </info> <title>Wired connections</title> </section> ========================================================== #: C/tips.page:14(desc) msgid "" "<link xref=\"tips-specialchars\">Special characters</link>, <link xref=\"mouse-middleclick\">middle click shortcuts</link>..." a bit poor list, does not incite to search for many good tips Suggesting: to add at least one more
(In reply to comment #0) > #: C/index.page:17(title) > msgid "" > "<media type=\"image\" src=\"figures/yelp-icon-big.png\">Yelp logo</media> > Desktop Help" > > This should not appear in translatable content as such. > but just "Yelp logo" and "Desktop Help" Actually I think it's made on purpose. You never know how another language is going to have to translate it and things such as word order may have to change, especially for RTL language where I guess the icon might end up at the end of the line. > shouldn't <desc> messages end without a full stop? Aren't descriptions sentences? Sentences should end with a period. > at [1] for example, make better visual for keys by using <kbd> HTML tag and > some CSS > See for example [2] > > [1] > http://library.gnome.org/users/gnome-help/3.0/shell-keyboard-shortcuts.html.en > [2] http://selfcoded.com/app/justnotes That's indeed a nice idea. I'd say it deserves it's own feature request. > I saw later that the topic is full of "iPod", should we use a more generic > term? or did iPod became a generic enough? I'm pretty sure the brand is used in a legitimate way here, i.e. to talk about an iPod and not just any music player device.
Please file separate bugs. There's just no way we can track this in a way it could be sanely closed. A few points on things that don't need bug reports: Regarding the extra titles for each page, please read http://projectmallard.org/1.0/mal_info_title.html . Translating documentation requires understanding the format just as much as writing it. The pot file from master should give you a little more info about them, because itstool shows two levels of parents in the comment, like (info/title) or (page/title). Somewhat better, though it still doesn't distinguish between link and text titles. In general, we need to devise a better way for translators to set various link titles for pages and sections. msgid "" "<media type=\"image\" src=\"figures/yelp-icon-big.png\">Yelp logo</media> Desktop Help" The image is inline. From a markup perspective, this is the same as "Click the <media src='microphone.png'>microphone</media> button." You don't want that split. We could special-case this in master with itstool. Something like this: <title><media type="image" src="figures/yelp-icon-big.png" its:withinText="no">Yelp logo</media> <span its:withinText="no">Desktop Help</span></title> Then again, perhaps we should look into not having alt text on the image at all. It's purely decorative. I'd have to ask the accessibility folks. The stuff in <comment> elements won't appear in master, which uses itstool. You're right about the make rules regenerating everything when you change a po file. But I have yet to figure out how to write portable make rules that do this correctly. The good news is that master builds much faster. Ending <desc> elements with a period (except for descs with lists of links, which end with an ellipsis) was a design decision. I'm happy to revisit it, but it should be discussed on gnome-doc-list. I'm open to discussing alternate wording for "More About". It's automatically generated for links to guides. They are basically "up" links. Usually, guides are names with noun phrases describing the topics they contain, and in those cases, "More About" works fairly well. I don't have any reliable way to programmatically decide what title to put on that, unless we introduce some style hints. We can override the title on a page-by-page basis, but that's going to be a pain in the long run. Maybe "More Information"? It doesn't imply a descriptive noun phrase like "More About" does. Anything regarding rendering (e.g. how key caps and combos are rendered) should be filed against yelp-xsl, please. For very obvious typos (e.g. misspellings or "the the") please just commit the fix.
(In reply to comment #2) > Please file separate bugs. I will do. Thank you for your comments
(In reply to comment #2) > Translating documentation > requires understanding the format just as much as writing it. I would say this is very arguable. I think the translator should be able to work from a paper copy. The rest is technical limitations. What ever format is used by the original, the translation work should be the same. Changing the source format for the same output should not change the translation work. When working on .po files, translators miss the final output, so they need hints about the strings logic (title, paragraph, label, error message, etc.). That's what we miss here. I kept Mallard's manual open while translating to understand what is what. Overall I think the translator's experience can be improved. > The pot file from > master should give you a little more info about them, because itstool shows two > levels of parents in the comment, like (info/title) or (page/title). Somewhat Good news! > better, though it still doesn't distinguish between link and text titles. In > general, we need to devise a better way for translators to set various link > titles for pages and sections. to my current understanding, the po file should include variants, even when the English strings are equal. (gettext can handle contexts) > Then again, perhaps we should look into not having alt text on the image at > all. It's purely decorative. I'd have to ask the accessibility folks. understood and agreed, minor, I won't push further. > The stuff in <comment> elements won't appear in master, which uses itstool. good news! > Ending <desc> elements with a period (except for descs with lists of links, > which end with an ellipsis) was a design decision. I'm happy to revisit it, I mentioned this because it seems the string appears in label-like places (drop down menu, and in More about sections). But that's very minor, I won't push it further. > I'm open to discussing alternate wording for "More About". It's automatically > generated for links to guides. They are basically "up" links. Usually, guides > are names with noun phrases describing the topics they contain, and in those > cases, "More About" works fairly well. I don't have any reliable way to > programmatically decide what title to put on that, unless we introduce some > style hints. We can override the title on a page-by-page basis, but that's > going to be a pain in the long run. Maybe "More Information"? It doesn't imply > a descriptive noun phrase like "More About" does. Thank for the explanation, I also read more of Mallard's doc, I start to understand better the whole thing. My confusion comes from the fact that I understand "more about" in a narrowing way (as in "More details about this topic on the current page"), instead of an extending way. I might have been mislead at first by the French translation which uses a narrowing wording (I guess the translator misunderstood "More about" as I did). Also I am not native English speaker so feel free to correct me. You use "Further reading" (only on guide pages?), which I understand better as extending the subject. Could this actually replace "More about"? See also this and that Further reading Desktop Help (I would place "See also" section before "More about" one) Or "More similar topics"? I filed bugs for: Bug 651357 - "Get more help", suggesting new topic on how to get more help Bug 651356 - minor content improvement Bug 651252 - Touching po file triggers rebuild of all languages Bug 651250 - make better visual for keys with <kbd>+CSS I dropped a few items.
I just pushed a fix for the typos.
Since we have the individual bugs, I'm going to close this one now.