GNOME Bugzilla – Bug 649877
Platform Overview -- minor feedback while translating
Last modified: 2012-03-31 13:42:07 UTC
Below are a few relatively minor points I found, as I was translating the document. If you need separate report for each, let me know! If you want patch, let me know too! I separate each issue with a ruler. -------------------------------------------------------------- C/telepathy.page:6(desc) msgid "Unified and integrated contacts and instant messaging" is Telepathy really this? I am no Telepathy expert, though for example I understood it can be used for a two remote players board game. We don't get it from the description. -------------------------------------------------------------- Some modules have reference to the project's website. I think it would be good that each module has such link. For example Telepathy page doesn't -------------------------------------------------------------- #: C/index.page:34(p) msgid "" "The GNOME platform provides a comprehensive development environment for " "graphical applications and other software. GNOME provides a comprehensive " "developer platform that allow developers to create professional software " "that is easy to use and aesthetically pleasing. Using the technologies in " writing style, the two first sentences are a bit heavy and redundant. Also, maybe add a sentence on module categories (core, graphical, etc.), as detailed lower on the page. -------------------------------------------------------------- #: C/gtk.page:6(desc) msgid "Graphical interfaces and core application support" On the "core appl support", I suppose it means gtk+/gtk and glib, but this is in the graphical section, and the gtk page actually talks only about gtk+/gtk maybe just "GUI"? -------------------------------------------------------------- #: C/gstreamer.page:6(desc) msgid "Plugin-based rich multimedia creation and delivery" IMHO it does not enlighten much an application developer on what GStreamer will do for him/her. In general, it could be good to unify the "one sentence" module presentation. I like best the WebKit way. As an application developer I understand that this is [not] what I need to use. The others are not all clear to me. -------------------------------------------------------------- #: C/gio.page:30(link) C/gio-network.page:20(link) C/d-bus.page:46(link) msgid "GIO Reference Manual" #: C/gio-network.page:21(link) msgid "Lowlevel network support" #: C/gio-network.page:22(link) msgid "Highlevel network functionality" These last two are subpages of GIO manual itself, I think they could be presented as a sublist: - GIO manual, especially: - low level section - high level section -------------------------------------------------------------- uniform presentation, all module pages have further references as a bullet list, except Keyring and GDA (at least)
a typo, #: C/telepathy.page:18(p) msgid "" "With the Telepathy Tubes API, you can even tunnel an arbitrary protocal over " ^^^^^^^^ --> protocol
#: C/clutter.page:26(p) msgid "" "Clutter comes with pre-defined actors for displaying solid colors, image " "data, text and custom high-precision 2D drawing using the Cairo API. Clutter " "also provides generic classes for structuring a user interface using both a " "box-packing model like GTK+, and a series of free-form \"constraints\"." could link to cairo overview page (and GTK+ page too)
clutter page is lacking a word about animations (which makes clutter interesting)
the "help" page seems more about authoring than, a user help system (F1)
(In reply to comment #4) > the "help" page seems more about authoring than, a user help system (F1) OK, I understand better as I am reading the Mallard web site. Maybe the overview text could be more clear?
#: C/index.page:34(p) msgid "" [snip] "GNOME, you can create high-quality software to meet and exceed your users' " "expectations. This document provides a high-level overview of the GNOME " "platform along with links to detailed documentation on each part of the " "platform." suggesting to start a new paragraph at "This document..."
The "More about" bottom section does not work well for this type of document, which consists of a main index page, and independent sub-pages. Also in the overview each sub-page has a list of links to know "more about". It is especially highlighted by some translations of "More about", like "Plus d'informations à ce sujet" (= more info _on_this_topic_) +--------------------------------------------------------+ GTK+ page <gtk overview> <link to more about gtk+> <link to more about gtk+> More about: <link to the index page, which has in fact no more about GTK+> +--------------------------------------------------------+
#: C/d-bus.page:42(p) msgid "" "GNOME provides full support for D-Bus using the GBus and GDBus APIs in GIO." What is GBus?
Created attachment 188826 [details] [review] 0001-new-file-.gitignore.patch
Created attachment 188827 [details] [review] 0003-added-reference-to-tech-s-web-site.patch
Created attachment 188828 [details] [review] 0004-use-the-same-structure-for-the-further-links.patch
Created attachment 188829 [details] [review] 0005-typo.patch
Created attachment 188830 [details] [review] 0006-cut-the-p-into-two.patch
Created attachment 188831 [details] [review] 0007-added-a-p-on-animations.patch
Created attachment 188832 [details] [review] 0009-added-xrefs.patch
Created attachment 188833 [details] [review] 0010-better-description-for-gtk.patch
Created attachment 188834 [details] [review] 0011-better-description-for-GStreamer.patch
Created attachment 188835 [details] [review] 0012-remove-redundancy.patch
Created attachment 188836 [details] [review] 0013-better-description-for-telepathy.patch
Created attachment 188837 [details] [review] 0014-removed-ref-to-GBus-added-xref-to-GIO.patch
I added patches for the issues above. That's many little changes. Tell me if you would like them in another form new file, .gitignore added reference to tech's web site use the same structure for the "further links" typo cut the <p> into two added a <p> on animations added xrefs better description for gtk better description for GStreamer remove redundancy better description for telepathy removed ref to "GBus" (?!?), added xref to GIO .gitignore | 15 +++++++++++++++ platform-overview/C/cairo.page | 1 + platform-overview/C/clutter.page | 12 +++++++++--- platform-overview/C/d-bus.page | 4 ++-- platform-overview/C/gda.page | 4 ++-- platform-overview/C/gstreamer.page | 16 ++++++++-------- platform-overview/C/gtk.page | 2 +- platform-overview/C/index.page | 15 ++++++++------- platform-overview/C/keyring.page | 10 +++++----- platform-overview/C/pango.page | 1 + platform-overview/C/telepathy.page | 6 ++++-- 11 files changed, 56 insertions(+), 30 deletions(-) About GIO networking references, I did not manage to create a nested list - GIO manual, especially: - low level section - high level section
Could someone have a quick look at the patches?
Review of attachment 188827 [details] [review]: ok.
Review of attachment 188828 [details] [review]: ok.
Review of attachment 188829 [details] [review]: ok.
Review of attachment 188830 [details] [review]: patch no longer applies against git master for platfrom-overview/C/index.page
Review of attachment 188831 [details] [review]: ok.
Review of attachment 188832 [details] [review]: great!
Review of attachment 188833 [details] [review]: I like it :)
Review of attachment 188834 [details] [review]: Much better. Thanks.
Review of attachment 188835 [details] [review]: Patch does not apply against current master branch.
Review of attachment 188836 [details] [review]: nice.
Review of attachment 188837 [details] [review]: nice catch
Great suggestions Luc. In the future, it would be best to attach each patch or set of two patches as separate bugs. There is a chance they would get looked at faster. Thank-you for your work.
Thank You Tiffany, for taking time to look at these, very much! Next time I'll write that many reports. (Honestly I am not sure that the delay is due to one or several reports. Personally, as a maintainer I prefer such tiny changes to be grouped together rather than being flooded by reports and all the administrative overhead. Maybe we can learn something from the history of this item. The honest reason is that GNOME Documentation is cruelly lacking of people. This is known. There is more work than people, so things take time. The only bad part on this specific story, is not the delay as such, in fact, but that nobody gave a head up. This despite several calls here or on the list. I tried to draw attention to get this fixed for 3.2 but did not get a single answer. After 3.2, I completely gave up on this document. I think that some authors do not see the value in translation (and do not care). The other side of the delay is that the translation is pending all that time. It is not very pleasant to try to provide good translations based on erroneous sources, and it is not the proper way to fix things on translations and not at the source. In the end when there are several documents pending with NO NEWS on the other side, you start to be frustrated and discouraged. And one of the first symptom of discouragement from the translators is that _they_stop_to_give_feedback_ upstream! I see this happening regularly. As an author I would take real care of translators, because they are the ones who will read completely and carefully your document. They do first class, priceless review. GNOME has too little resources to neglect this. There is another thing that does not ease the situation: the tools and process that we use do not support quick fluent review-feedback-correction loops. There is definitely something to improve here also. For this specific document, my understanding is that the author considers it as a "moving target" and is planning to rewrite it. So very personally, I don't think I will spend much more efforts on translating it. I hope that you did not loose your time by reviewing this changes. But at least you made me happy, thank you again for your attention! Do you want me to check the two patches that failed?
Hi Luc, The good news is that the Gnome Documenation Team is growing, but we do need more people to work on developer docs. It is also true that this module is being rewritten and a moving target. Such a rewrite has actually been started, but I decided to apply your patches anyways, as I believe it will be a quite a while before the new docs will be done. We may also reuse some of the content. Thank you very much for filing the bugs and not just using the translation to fix the problems. I really appreciate this :-) So the two patches that did not apply... one was a paragraph split and one a redundancy removal. If you have time to check the patches, that would be good. Also, there is #docs on irc if things are taking a while and you want to ping someone. You may be correct that it was not the size of the bug that caused the delay. It may be that it took me personally a while to look at it because of this reason, but I am new to devel-docs, so I first saw the bug just over a month ago. I would have fixed it then if it was smaller. Thanks for everything. Tiffany irc nick: mimiico