After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 673516 - documents-tracker.page is too technical and needs simplification
documents-tracker.page is too technical and needs simplification
Status: RESOLVED OBSOLETE
Product: gnome-documents
Classification: Core
Component: documentation
3.13.x
Other Linux
: Normal major
: ---
Assigned To: Maintainers of Gnome user documentation
Maintainers of Gnome user documentation
Depends on:
Blocks:
 
 
Reported: 2012-04-04 15:55 UTC by Pallavi
Modified: 2021-07-05 11:31 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
patch for documents-tracer.page (2.09 KB, patch)
2012-04-04 15:55 UTC, Pallavi
needs-work Details | Review

Description Pallavi 2012-04-04 15:55:02 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.
Comment 1 André Klapper 2012-04-05 10:02:05 UTC
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).
Comment 2 André Klapper 2012-09-15 18:20:30 UTC
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.
Comment 3 Kat 2013-10-26 00:28:20 UTC
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
Comment 4 Kat 2014-09-23 12:02:09 UTC
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.
Comment 5 GNOME Infrastructure Team 2021-07-05 11:31:27 UTC
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.