291866 - Make the "How to Use Help" doc non-browser-specific

Status: RESOLVED FIXED

(SeaMonkey :: Help Viewer, defect)

Description

[Jeff Walden (gone starting June 8)]

Stuff to do:

-Change the "searching for words like" reference to just use &brandShortName;
instead of both it and &vendorShortName; (or possibly just to "the" or some
similarly generic word).  Nvu 1.0PR to some extent uses the toolkit Help Viewer,
and in their stuff (1)==(2)=="Nvu" -- hence they get 'words like "Nvu" and "Nvu"
could...'.
-Divorce images used from Firefox-ness.  The images are currently stored on m.o
along with all the Firefox Help images, which is completely idiotic.  They
should either be packaged or we should make the text fully usable without them
(preferably the latter).
-The flavor text for Back/Forward/Home is completely specific to use of Help
within a browser-like application and needs to be rewritten.
-The first bullet under Search Tips may be necessary for an application like
Firefox, but it's not applicable to normal applications.  We should probably
remove it, even if this may not be an improvement for Help within Firefox.

Comment 1

[Steffen Wilberg]

How about ripping out the "Retracing your steps" section entirely? 
Click the Back button to move back? To print, click the Print button? This is
ridiculous. If we're concerned that users don't know what the buttons do, we
should rather default to the (bulky) icons + text mode.
Removing that section would get rid of all the images in that doc.

As for the other images, bug 249744 looks interesting. That doesn't work for
screenshots of whole dialogs though.

> -The first bullet under Search Tips may be necessary for an application like
> Firefox, but it's not applicable to normal applications.  We should probably
> remove it, even if this may not be an improvement for Help within Firefox.
I consider this quite important for Firefox, and it doesn't do much harm on
other apps, which are likely to have some relationship with the Internet as well.

Comment 2

[Jeff Walden (gone starting June 8)]

Attachment: Fix (diff -u8w)

Comment 3

[Jeff Walden (gone starting June 8)]

Attachment: Fix (the real version)

Somehow when this got moved a whole bunch of tab characters got added to it. 
I've removed them and reformatted where necessary.  I removed the Retracing
section like you suggested, and in its place I added a sentence to the end of
the Finding section that more or less communicates the (important parts of the)
stuff that got removed.

Comment 4

[Steffen Wilberg]

Comment on attachment 183956 [details] [diff] [review]
Fix (the real version)

>diff -u -4 -w -r1.1 welcome.xhtml
You attached the diff -uw twice :)

Please also remove this line from the "contentsBox" since you removed the
"retracing your steps" section:
  <li><a href="#retracing_your_steps">Retracing Your Steps</a></li>

>-		 <li><strong>Index</strong> lists topics alphabetically.<br/>Click an index entry
>-		 to view information on that topic.</li>
>+    the topic you want to read about.  If your search doesn't return any
>+    topics, try typing fewer words or a different combination of words.</li>
>+  <li><strong>Index</strong> lists topics alphabetically.<br/>Click an index
>+    entry to view information on that topic.</li>
> 		 <li><strong>Glossary</strong> lists definitions alphabetically.<br/>Click
> 		 a glossary term to see its definition.</li>
The wording is fine - just add newlines after <br/> tags to improve the
readability of the source.

>+  <li>Avoid being too broad with your search.  For example, a common word like
>+    &quot;dialog&quot; will likely return more pages than you want.</li>
> 	</ul>
I don't know if your patch from bug 294232 improves Search in this respect, but
right now searching for "dialog" doesn't return any results at all. "Tab" or
"download" are too browser-centric. "Options" doesn't apply to Linux. How about
"page"?

r=me anyway.

Comment 5

[Jeff Walden (gone starting June 8)]

Attachment: Updated in response to review comments

(In reply to comment #4)
> Please also remove this line from the "contentsBox" since you removed the
> "retracing your steps" section:

Done.  I also remembered to remove the item from help-toc.rdf as well this
time.

> I don't know if your patch from bug 294232 improves Search in this respect,

It doesn't.  The patch fixes functionality we've been claiming to have
according to <http://www.mozilla.org/projects/help-viewer/content_packs> (which
is linked from
<http://www.oreillynet.com/pub/a/mozilla/2005/05/06/firefoxglossary.html>,
interestingly enough).	We never used the functionality (see the code at
<http://lxr.mozilla.org/mozilla/source/browser/locales/en-US/chrome/help/firebirdhelp.rdf#28>),
so it has no visible effect on Firefox Help.  However, it might have an impact
on other content packs in existence.

> right now searching for "dialog" doesn't return any results at all. "Tab" or
> "download" are too browser-centric. "Options" doesn't apply to Linux. How
> about "page"?

"page" works for me.  Funny - I didn't even bother to think about the
possibility that "dialog" would return nothing.

Incidentally, I noticed another problem this patch fixes that hasn't yet been
mentioned, just for the record - we referred to the "Enter" key once even tho
it's "Return" on Macs, which would have been ugly to hack around without the
platform-specific entities.  It may be worth moving the keyboard entities into
toolkit at some point in the very near future to make this stuff easier for
Help viewer users.

Anyway, this is getting close to the end for Deer Park, so this might end up
getting punted a little, but that's not really a problem as long as we get it
in before the l10n freeze (and thus before the 1.8 xulrunner preview release).

Comment 6

[Jeff Walden (gone starting June 8)]

Comment on attachment 184383 [details] [diff] [review]
Updated in response to review comments

>+  <li>Avoid being too broad with your search.  For example, a common word like
>+    &quot;page&quot; will likely return more pages than you want.</li>

A last ueber-nit I'll fix before checkin: change "pages" to "topics" so we
don't have the oddness of "page" mentioned adjacently with two separate
meanings.

Comment 7

[Jeff Walden (gone starting June 8)]

Fix checked in.