77040 - Preferences Help in plain language (and gives "default" values)

Status: VERIFIED WORKSFORME

(Documentation Graveyard :: Help Viewer, defect)

Description

[Peter Lairo]

Help File that explains Preferences Settings in Plain Language (and gives
"default" values)

+-Help File--------------------------------------------+
*Preferences Settings*

Category:

- Navigator - This section contains setting that affect the browser part of Mozilla

Category Contents:

Subsection: Navigator (main subsection)

-- When Navigator starts up display (default = Home Page)

--- Blank Page: With this setting, when you load your browser no web page will
be loaded or displayed. All you will see is your browser window with no content
in it ("blank"). This allows the browser to load more quickly for situations
where you don't want to access a web page at first, but might rather want to...

--- Home Page: This setting will load the web page you defined as you "home
Page" (see preference for "homepage" below this setting). If you want you
browser to start on a particular ...
+-------------------------------------------------+

I know this will be a lot of text, but one thing missing in most apps is a
helpfile that explains settings *as they appear* in the app. Of course the help
section should be indexed and searchable. 

This would kill two birds with one stone: (1) display the default values AND (2)
give a location that explains the apps settings, thus restoring the jaded
publics' belief in the usefullness of helpfiles.

Comment 1

[Peter Lairo]

If someone sets up the structure, I might be able to contribute some of the text
(not much though).

Comment 2

[Zach Lipton [:zach]]

this belongs in documentation. the help component is for bugs with the 
help browser itself.

Comment 3

[Boris Zbarsky [:bzbarsky]]

Decent idea. Peter, would you be willing to create some verbiage as a starting
point?

Comment 4

[Peter Lairo]

I would love to, but unfortunately I am swamped with work in my "paying" job :(
I might be able to contribute in a few weeks.

A "small" example of the type of wording is in my initial post for this bug.

************************************************
Rule #1: should be understandable for someone without PC knowledge.

Rule #2: Should include an example or description of what the feature does or
looks like when changed.

Rule #3: Should be as short as necessary

Rule #4: Info should be presented in modules or subsections separated physically
(e.g. definition, example, default value)
************************************************

I only wished all help files were structured like this :)

Comment 5

[Jayesh Sheth]

Gunnar has some great help on Mozilla's Preferences:
http://mozilla.gunnars.net

Maybe we can use his work as a jumping off point. (I have already emailed him
about this.)

Comment 6

[Daniel Wang]

Does Mozilla Help support variable string? Otherwise putting default
values in would be a localization nightmare

Comment 7

[Brant Gurganus]

New Help was just dumped into the tree and it looks like this is pretty well
documented.

Comment 8

[Peter Lairo]

I (briefly) looked at the help system in build 20030131 and the help I looked at
(Helper Applications) violated Rules #1, #2, and #4 from comment #4. Reopening
pending proper fix.

Comment 9

[Daniel Wang]

> Rule #1: should be understandable for someone without PC knowledge.

looks fine to me. Mozilla has context-sensitive Help for Preferences

> Rule #2: Should include an example or description of what the feature
> does or looks like when changed.

worksforme

> Rule #4: Info should be presented in modules or subsections separated
> physically (e.g. definition, example, default value)

I am against this rule. The Help is meant for task-oriented help, not
for user guide or reference manual. Places where we need Preferences
reference is bug 195845 and bug 158384, not Help.

I think this bug should be FIXED.

Comment 10

[Daniel Wang]

Peter Lairo, please give an sample rewrite so we know what we are looking for

Comment 11

[R.J. Keller]

Hey Nilson, you're really good at making user-friendly documentation. Want a
crack at this?

Comment 12

[Nilson Cain]

Yea :)  What all files are covered?  All the
/mozilla/extensions/help/resources/locale/en-US/cs_xxx_prefs_xxx.html?

Comment 13

[Daniel Wang]

yes

-> Nilson

Comment 14

[R.J. Keller]

yup

Comment 15

[James "Kovu" Russell]

I think this should be futured because I think it's a good idea to wait until
Firebird takes over. When that happens, this project will be a lot simpler than
it is with Seamonkey. If we're deprecating Seamonkey I just don't see writing
all this text just to cut most of it out when Firebird's cleaner Prefs take over.

Comment 16

[Daniel Wang]

Resolve as worksforme.

The bug description is too general. If you find something in Help that needs
clear up, feel free to file a new bug. Also, Help is not the place to "fix"
Preferences dialog. I prefer that we fix the UI rather than bloating Help.

Peter, got time for QA? I've got my hands full with doc on the Web site and have
no time to QA the Help component.

Comment 17

[Stefan [:stefanh]]

v