GNOME Bugzilla – Bug 696605
help: Better/more detailed description for USB redirection
Last modified: 2016-03-31 13:22:07 UTC
Would be nice to have some screenshots of USB redirection in action.
Created attachment 239849 [details] [review] help: Add screenshots for USB redirection
Review of attachment 239849 [details] [review]: Don't use screenshots unless you absolutely have to because screenshots need to be "translated" which is very hard to do and the translators probably don't need the extra work. Because the screenshots do not demonstrate anything that cannot be described, they are not needed on this page. You can improve the page by adding step-by-step instructions on how to set up USB redirection. ::: help/C/usb-redirection.page @@ +33,3 @@ appear as directly connected to the remote computer.</p> + <media type="image" src="figures/usb-redir.png" For future reference… screenshots work best inside a <figure> tag with a title and/or a description. @@ +34,3 @@ + <media type="image" src="figures/usb-redir.png" + width="500" height="303"> Do not specify the width and height as that may make the text too small to read. Yelp will scale the screenshot to something sensible itself. It is best to take the screenshot with the main window at 825 pixels wide so that the online help also looks pretty while still being at least somewhat useful. @@ +35,3 @@ + <media type="image" src="figures/usb-redir.png" + width="500" height="303"> + <p>Choosing USB devices to redirect.</p> These descriptions should be a bit more detailed as they are fallbacks in case a screenshot is not displayed. "Screenshot showing the preferences for setting up USB device redirect." would be more appropriate.
Review of attachment 239849 [details] [review]: 1. Whatever happened to 'a picture is worth a thousand words'? 2. How is translation of screenshots difficult? You just take screenshot of the same view in the target language. How hard is that? If that is not possible for translators, they can simply describe more instead based on the screenshot. ::: help/C/usb-redirection.page @@ +33,3 @@ appear as directly connected to the remote computer.</p> + <media type="image" src="figures/usb-redir.png" I simply followed the existing docs xml. :) I'll keep that in mind. Thanks. @@ +35,3 @@ + <media type="image" src="figures/usb-redir.png" + width="500" height="303"> + <p>Choosing USB devices to redirect.</p> Sure.
The key point is that the screenshots did not demonstrate anything that cannot be described. (In reply to comment #3) > How is translation of screenshots difficult? You just take screenshot of the > same view in the target language. How hard is that? This is exactly why it is hard: your environment needs to be recreated by someone else. > If that is not possible for > translators, they can simply describe more instead based on the screenshot. Translators do not add content, they simply translate.
(In reply to comment #4) > The key point is that the screenshots did not demonstrate anything that cannot > be described. That is true for almost anything, including the already added screenshots from docs team. > (In reply to comment #3) > > How is translation of screenshots difficult? You just take screenshot of the > > same view in the target language. How hard is that? > > This is exactly why it is hard: your environment needs to be recreated by > someone else. That is an interesting issue. However around the time gnome reaches stable, we usually start to roll out live images that translators can use? > > If that is not possible for > > translators, they can simply describe more instead based on the screenshot. > > Translators do not add content, they simply translate. Perhaps they could be allowed to do so? This is plan B, anyways.
(In reply to comment #5) > (In reply to comment #4) > > The key point is that the screenshots did not demonstrate anything that > > cannot be described. > > That is true for almost anything, including the already added screenshots from > docs team. Surely we could remove those screenshots if they don't add any value that could not be expressed in words. > That is an interesting issue. However around the time gnome reaches stable, we > usually start to roll out live images that translators can use? ftp://ftp.gnome.org/pub/gnome/misc/testing/ had ISOs for 3.7.90 and 3.7.92 only. Most strings get translated only in the last weeks and hence were not included in 3.7.90. If you have an idea how to create ISOs more regularly that would certainly help. > > > If that is not possible for > > > translators, they can simply describe more instead based on the screenshot. Don't get it, especially not the "simply" in that sentence. It's not supported to add a random long new paragraph just for language X to the translation and define where it should be shown. > Perhaps they could be allowed to do so? This is plan B, anyways. I'm pretty sure that nobody would stop you from designing and implementing that in our L10N/I18N infrastructure. :)
(In reply to comment #6) > (In reply to comment #5) > > (In reply to comment #4) > > > The key point is that the screenshots did not demonstrate anything that > > > cannot be described. > > > > That is true for almost anything, including the already added screenshots from > > docs team. > > Surely we could remove those screenshots if they don't add any value that could > not be expressed in words. Then they get removed. :) I'm waiting for a patch from docs team now. > > That is an interesting issue. However around the time gnome reaches stable, we > > usually start to roll out live images that translators can use? > > ftp://ftp.gnome.org/pub/gnome/misc/testing/ had ISOs for 3.7.90 and 3.7.92 > only. Most strings get translated only in the last weeks and hence were not > included in 3.7.90. You are telling me that translators translate the docs too in this time? I see a lot of translation commits all the time but I haven't yet seen *any* translation for docs in Boxes yet. Please keep in mind that I was only talking of docs translation here and not small/simple strings (preferably with comments) that come from code and are *typically* much easier to translate than explanations from docs. > If you have an idea how to create ISOs more regularly that > would certainly help. I don't think there is any "ideas" needed here. They go out ASAP AFAIK and 3.8.0 one is not out yet because of some issues we are facing. > > > > If that is not possible for > > > > translators, they can simply describe more instead based on the screenshot. > > Don't get it, especially not the "simply" in that sentence. http://en.wikipedia.org/wiki/Simple If that was a sarcastic way of saying that what I described is not simple, please point out how its not simple rather. > It's not supported > to add a random long new paragraph just for language X to the translation and > define where it should be shown. Random? Where did I say something about adding *random* stuff? > > Perhaps they could be allowed to do so? This is plan B, anyways. > > I'm pretty sure that nobody would stop you from designing and implementing that > in our L10N/I18N infrastructure. :) Perhaps I'll look into that after doing all the gazillion things on my todo but when I do, would be nice to know what exactly you are asking me to do.
Created attachment 240913 [details] [review] Instructions to usb-redirection, fewer screenshots
(In reply to comment #8) > Created an attachment (id=240913) [details] [review] > Instructions to usb-redirection, fewer screenshots Completes USB page without screenshot, removes extraneous screenshot from create.page, adds more descriptive alt text to screenshots in interface.page.
Review of attachment 240913 [details] [review]: This patch has 3 separate changes, 2 that you pointed out in the commit log and 1 that I pointed out in in inline comment. Changes themselves are good. ::: help/C/interface.page @@ +28,3 @@ + <media type="image" src="figures/collection.png"> + <p>Screenshot showing the Boxes collection view.</p> Change here seems to be about removing the size restrictions so I'd rather you put this in a separate patch.
Created attachment 240999 [details] [review] Del create scrnsht, interface scrnsht text modded
Created attachment 241000 [details] [review] Instructions added to usb-redir in lieu of scrnsht
(In reply to comment #10) > Change here seems to be about removing the size restrictions so I'd rather you > put this in a separate patch. Patches separated.
Review of attachment 241000 [details] [review]: ::: help/C/usb-redirection.page @@ +30,3 @@ of device into your computer. <sys>USB redirection</sys> makes devices + plugged into your local computer available in the machines you are + connected to in <app>Boxes</app>. For instance, a pen drive or a webcam will Pen drive? USB flash drive is more accurate and common, I think. @@ +38,3 @@ + already open, click the properties button in the toolbar.</p></item> + <item><p>Click <gui style="menuitem">Devices</gui> in the sidebar.</p></item> + <item><p>Ensure <gui style="menuitem">Redirect new USB devices</gui> is Is "Redirect new USB devices" really in a menu? I've looked at the source code (as boxes is crashing on F19 for me), and it looks like that's just a label on the properties page. @@ +40,3 @@ + <item><p>Ensure <gui style="menuitem">Redirect new USB devices</gui> is + switched to <gui style="switch">ON</gui>. + <gui style="menuitem">USB devices</gui> connected to the host machine are Same as above.
Created attachment 241042 [details] [review] Steps added to usb-redir, no screenshot
Comment on attachment 241042 [details] [review] Steps added to usb-redir, no screenshot Pushed to master in commit 990017de52abe50363b02ad26e109681881ea733
Mike commited the patch so let's close this bug.