GNOME Bugzilla – Bug 673516
documents-tracker.page is too technical and needs simplification
Last modified: 2021-07-05 11:31:27 UTC
Created attachment 211310 [details] [review] patch for documents-tracer.page The point of this page is to explain to users why they may not be able to see any documents in the new GNOME Documents application. The page is written in a technical manner, and isn't that useful to most users Here is a new simplified version of documents-tracer.page which excludes going too deep into more technical terms.
Review of attachment 211310 [details] [review]: Hi Pallavi, thanks for the patch! Some comments below: ::: gnome-help/C/documents-tracer.page @@ +23,3 @@ </comment> + <p>The <link href="https://live.gnome.org/Design/Apps/Documents">GNOME document</link> uses <link href="https://live.gnome.org/Tracker">Tracker</link> to read and store information about the document on the system. The reason for which the GNOME Document may not be able to read document could be due to the errors in Tracker settings. Make sure that the following settings are done</p> Personally I really would not link to the design page for that application. Which additional value does it provide to somebody looking for help? (If a link would be needed it would be https://live.gnome.org/GnomeDocuments anyway. :) Plus (this happens several times): The application is not called "the GNOME Document" but simply "Documents". You can use <app> as the Mallard markup for application names (also in other places of this patch, also for "Tracker"). Plus you cannot "do settings" - this needs rephrasing. @@ +26,3 @@ + <steps> + <item><p>Tracker is turned on</p></item> + <item><p>Check whether the Tracker is indexing the right <link href="http://freedesktop.org/wiki/Software/xdg-user-dirs">directory</link></p></item> I would treat "Tracker" as a name of an application here and in other places, so using "<app>" markup and dropping the "the" in front of the name. Only one "directory", not "directories"? @@ +27,3 @@ + <item><p>Tracker is turned on</p></item> + <item><p>Check whether the Tracker is indexing the right <link href="http://freedesktop.org/wiki/Software/xdg-user-dirs">directory</link></p></item> + <item><p>Check if the Tracker had indexed any files before</p></item> This is better than the previous "help" in this file, but still leaves me wondering: *How* exactly can I check this? @@ +29,3 @@ + <item><p>Check if the Tracker had indexed any files before</p></item> + </steps> + <p> You can run the following command to make the tracker to recursively scan the correct directory, </p> Actually these are two, hence "commands" (plural).
To me the patch does not simplify things but confuses me a bit more, e.g. by linking to the "folders" specification for reasons that I don't understand. :) The page has changed a bit in the meantime but could still get some improvements, e.g. how to check if tracker is actually running.
Documents only looks at specific file types (.odt, .pdf). This is much more likely to be a problem than tracker not working. If tracker is not working, the user is unlikely to be able to do anything. We can warn the user that it may sometimes take a while for files to be indexed (for example, on first run). I would delete this page and create a new one for "why can I not see my documents?" to which should address the following: * are they the right file type? * are they in the right place? * the files are currently being indexed
This page is now in the gnome-documents repository and has been renamed to prob-no-show.page. It currently covers supported document types, indexed locations and still has the tracker blurb that this bug is about. I'm not convinced that there is much a user can do about tracker not working either… although I agree that the tracker blurb is quite unhelpful.
GNOME is going to shut down bugzilla.gnome.org in favor of gitlab.gnome.org. As part of that, we are mass-closing older open tickets in bugzilla.gnome.org which have not seen updates for a longer time (resources are unfortunately quite limited so not every ticket can get handled). If you can still reproduce the situation described in this ticket in a recent and supported software version, then please follow https://wiki.gnome.org/GettingInTouch/BugReportingGuidelines and create a new ticket at https://gitlab.gnome.org/GNOME/gnome-documents/-/issues/ Thank you for your understanding and your help.