Closed Bug 46917 Opened 20 years ago Closed 11 years ago

Mozilla online help contents tracking bug

Categories

(Documentation Graveyard :: Help Viewer, enhancement, P3)

enhancement

Tracking

(Not tracked)

RESOLVED FIXED

People

(Reporter: stephend, Assigned: danielwang)

References

(Depends on 1 open bug)

Details

(Keywords: meta, Whiteboard: was "Sanitizing Netscape's documentation for Mozilla users")

Attachments

(2 files)

From Bugzilla Helper:
User-Agent: Mozilla/4.74 [en]C-NSCPCD  (Win98; U)
BuildID:    Any

I would be willing, in my spare time, to "sanitize" Netscape's help files for 
Mozilla, since the codebase is so close, it shouldn't be much more than grueling 
keyboard entries :-).  Nominating myself and possibly James Russell (Kovu) for 
this task.  I've already chatted with Asa about this, and there are a couple 
more people who seem interested.  I could only do one platform, Windows 98, but 
still...

Reproducible: Always
Steps to Reproduce:
1.None
2.
3.

Actual Results:  							

Expected Results:
All others are welcome to join, just CC: yourself to this list for updates.

ALSO: I would (as should all others) be willing to sign an NDA for this, if 
needed.
NDA Probably not needed since the help files were made public in PR1 and will
again be public in PR2.  
Accepting for now.

Thanks for your offer to help! As Asa indicated, the help will be made public in
PR2...We're cranking away on the files...Expect an update next week about when
the files will be available. The files are HTML/XML and are cross-platform. I'll
reassign when appropriate...with stephendonner as the lead on this (i.e., I'll
reassign to you when the files are available).
Status: NEW → ASSIGNED
Well, since I'm now QA for the Mail/News team, I don't think I'll have any spare
time to do this.

Thanks!
Resolving to fixed to get off radar. The help files are checked into the 
repository---though not part of the builds per se.
Status: ASSIGNED → RESOLVED
Closed: 19 years ago
Resolution: --- → FIXED
verified.  Ian has been slaving away at it for some time now ;-).
Status: RESOLVED → VERIFIED
Zach Lipton and I are taking on the task of "sanitizing" Netscape 6 help
documentation for Mozilla. The files that need updating are here:
http://lxr.mozilla.org/mozilla/source/extensions/help/resources/locale/en-US/

I'm taking the following docs to start with:

composer_help.html - JR
glossary.html - JR
help-toc.rdf - JR
help_index.html - JR
welcome_help.html - JR

We'll use this bug to make sure no one duplicates effort on the same docs.

Zach, anyone else, please list any files you're taking.

And if anyone has already started on any of these files, please scream now.
Status: VERIFIED → REOPENED
Resolution: FIXED → ---
I'll take 

nav_help.html
validation_help.html
using_priv_help.html
using_certs_help.html
ssl_help.html
ssl_page_info_help.html
privsec_help.html
privacy_help.html
passwords_help.html
mail_help.html
im_help.html

to start
Adding Sean Cotter to cc list.

For various reasons, the security/PSM content is the only content that Netscape 
is updating for Mozilla itself. The rest of the content has been checked in 
once, and now rests in the capable hands of Kovu and Zach for sanitizing for 
Mozilla. But you guys should coordinate efforts with Sean, who is the security 
doc writer, as he is responsible for some of the files Zach lists. Sean will 
continue to modify security-related docs for Mozilla. 
Zach, Kovu: right on! cc'ing myself.
Do the security files need updating for psm2 in the first place? We might 
be better off pretending I didn't list any security files.

Zach
I have more recent versions of the following files that aren't yet updated, and 
expect to work on them more or less continuously for the next next couple 
of months:

cert_concepts_help.html
cert_dialog_help.html
certs_help.html
glossary.html
passwords_help.html
prefs_help.html
privacy_help.html
privsec_help.html
ssl_help.html
ssl_page_info_help.html
using_certs_help.html
using_priv_help.html
validation_help.html

All of these files are related to PSM 2.0 in one way or another. Should be fine 
to work on any other files in the en-US directory.

I will also be making changes to help-toc.rdf and help.js.

Once a reasonable first pass on these files is checked in (within the next 
couple of weeks) I'll announce it in the crypto newsgroup and make sure everyone 
cc'd on this bug also gets notified. Suggestions are welcome. 

cc'ing Bob Lord.
*** Bug 77629 has been marked as a duplicate of this bug. ***
I would like to help document the browser part of Mozilla. I have already 
documented the FIle menu, Edit menu, View menu, and all the prefs. Now I just 
have to figure out where the HTML files go. 

I am doing this in English for Win 98. 
How and where do I get the existing documentation? From daily builds? I 
currently have R.9 and it does not have any documentation in the directories 
mentioned above. 
I think that they are in a help.jar file in the bin/chrome directory. If you
unzip the jar you should see the contents of the help system (I think).
Chuck, I think a higher-level plan is in order before you document further, else 
you may do a lot of work for naught. The help in Netscape 6, for instance, is 
not by UI feature, but is task-based instead. So, there is no documentation for 
each of the menu items per se. In general, a task-based approach to end-user 
help is preferable to a feature-based approach. 

I suggest that you coordinate any effort with Zach and Kovu.
Asa, that is correct. Chuck, in order for you to edit the help files, view bug 
77629 for instructions. 

So, Rudman - what you are saying is that the help is organized by tasks that 
can be done on the program (such as editing prefs), and where those tasks are 
described, they tell you how to find it in the UI?
Is there a possibility that maybe in the help, there could be a listing of all 
the menus and a link to the task they accomplish? For instance, the listing of 
the edit menu would have a choice Preferences that would bring up the pref help?
I will be changing the references to NS 6 in the help files, if it's all the 
same to everyone. 

ps. Found the help.jar file in the daily build and am modifying it. 
I think it would be a good idea to have a reference for what all the menu items 
do, and what all the preferences do, in addition to task oriented help. Once 
people get to know the browser, they want to find out the details of how 
something works. That's usually the part I have the most trouble finding: 
detailed reference material. Usually I can't find any at all!

I made a program to manage the index file and index entries for each help file. 
This program will allow the user to enter keywords for an html file (like 
menufile.html) or a target (like menufile.html#save). Then it will generate the 
help_index.html file (which contains all the index entries). 

Next, I made some changes to the help screens. How do I upload them? To where? 
They are in the correct directory structure for the help.jar file. Should I zip 
them up in an updated JAR file and upload that somewhere? 

Thanks. 
I don't see that as a problem in removing references to Netscape 6 or anything 
like that. I also think it is alright that you document some of the menus. 
There is no reason to go overboard either. For cut and paste, one sentence is 
all that is necessary and you can group them together. Also, if you talk about 
the bookmarks menus, please also link to the part that talks about bookmarks in 
general.

It would also be great if you wrote an index. 

The help also needs a built-in search engine. If you have experience with that 
kind of thing, I think you can do it in javascript probably.

Blocks: 67376
See bug 80879 about updating Index.
Also see the new bug I made: bug 83862 about a search engine.
Chuck R: I don't know if you are aware of this, but look above where it this 
bug blocks a bug. That bug it blocks is a tracking bug, used to track similiar 
bugs.
re Comments From rudman@netscape.com 2001-06-01 11:29.
Microsoft supplies both forms of help (context sensitive and task oriented), 
while we don't usually point to microsoft <stddisclaimer/>

UI Help is currently rather useless because we don't have help and whatsthis 
buttons sprinkled throughout the ui.  The reason we didn't do that is we didn't 
have help until recently.  (this is cyclic) Currently people in UID are trying 
(occasionally) to discourage inline comments because they (we=them+me) prefer a 
cleaner ui where users can rely on a help button for an explanation of each 
element.

hrm, i'm slighlty confused is this bug a general help bug? it seems that way 
even though it has a specific subject and should therefore have a limited 
scope...
URL: Any
Timeless, context-sensitive help can be task-oriented. Help that is not
context-sensitive can also be task-oriented. My comments were more about a
philosophical approach to the nature of help. Chuck R.'s approach seemed more
like a reference of each UI item, which isn't a task-oriented approach. I think
that if each UI item, like each menu item, requires help, then the UI is in
trouble. The best form of help, in a sense, is when it is embedded directly in
the UI, thus obviating the need for separate help content. Menu items, if done
well, should be self-evident as to their meaning. Some higher-order tasks that
involve use of the menu items is what could be documented in the help.  

Timeless, I don't understand your comment "they (we=them+me) prefer a 
cleaner ui where users can rely on a help button for an explanation of each 
element." I don't think that is an objective of most anyone currently working on
help, and it shouldn't be the objective of anyone working on the UI. While it's
great to strive for a "cleaner UI," that does not exclude the possibility of
making the UI elements clear enough so that independent help content is
unnecessary or kept to a minimum.

This bug is larger than the summary might suggest, but that's in part because
ideas of what the help should be have surfaced at the same time as the effort to
sanitize the Netscape help has gotten underway. Implicit in the Sanitize bug is
that the approach to help in the Netscape content is the preferred way of
providing help for Mozilla. It would be a waste of time if different schemes for
providing help for Mozilla were undertaken simultaneously. Since the effort to
sanitize the help has gotten underway, this bug is useful as a way of
integrating that effort, and it just happens that variants to the general
approach in the [soon-to-be-sanitized] help have surfaced here. It remains to be
seen if those variants can be encompassed in the sanitized help.

A few things to note about help in general: Keep footprint size in mind. This
might be more crucial when considering, say, search engines rather than the
content files. But it's also a consideration for content files if screenshots
and graphics are being added. Also, keep in mind that the help should be
localized---both writing style and graphics should accommodate ease of translation.

Chuck R, can you please elaborate on what you mean by changes to the "help
screens"? Can you attach something to this bug to help us understand that? Send
me a zipped jar directly, if you want. Copy oeschger@netscape.com, too, if
you're including index files, as he was working on an indexing scheme as well.
Reminder:

For the time being, please don't attempt to modify any of the following files:

cert_dialog_help.html
certs_help.html
glossary.html
passwords_help.html
prefs_help.html
privacy_help.html
privsec_help.html
ssl_help.html
ssl_page_info_help.html
using_certs_help.html
using_priv_help.html
validation_help.html
help-toc.rdf

These will be changing quite a bit over the next few weeks as I complete the
help for PSM 2.0 and some related features. Work in progress, regardless of
what's currently checked in, can be viewed at
http://www.mozilla.org/projects/security/pki/psm/help_20/#docs.



Just a quick note on the state of the help files in mozilla: I've just updated 
many of the main help in mozilla/extensions/help/resources/locale/en-US with the 
stuff that the NS help authors have been working on: nav_help.html, 
composer_help.html, mail_help.html, and so on. The table of contents itself is 
not quite up to date, but I will update that too shortly.

The new content reflects some recent changes in the UI, and the screenshots have 
also been updated for the new Modern skin. As before, if you have new content or 
other things you want to go into the help viewer, that is _great_. I just didn't 
want anyone to spend a lot of time working on updates to the files I just 
updated there, which are basic task-oriented docs on the browser, the mailnews, 
the composer, etc., especially when there are so many other cool things we could 
put in the help viewer--the keywords document, more developer-ish type stuff 
(?), mozilla.org content, theme documentation (?), bugzilla HOWTOs, build stuff, 
javascript how-to stuff, venkman doc, inspector docs, mozilla community stuff, 
chatzilla docs, docs for the extensions, open source stuff,...

Note that several of the context-sensitive help buttons surfacing in the 
preferences panels and other dialogs (cf. bug 46226) also point at "dummy" help 
files in mozilla (with names like cs_nav_advanced.html, etc.) that say something 
like "context sensitive help: write me!" and give the name of the file. That's 
another set of content that really wants writing.

I think I also checked in an enlarged albeit still lame index file. The security 
docs and some of the others in this repository have the index markup in them, 
and a little python script generates help_index.html from these. Would love some 
help making this indexing work better. 

Just checked in zach's changes to nav_help.html on the mozilla branch/trunk. Way
to kick ass, zach!

*** Bug 112271 has been marked as a duplicate of this bug. ***
Got the context-sensitive help files from the commercial side into mozilla this
morning. These are the files that begin cs_nav_* and display when you click the
Help button in the prefs dialog and in other places where it's available. It did
say "write me", now there should be some content (albeit content that still
needs sanitizing and Netscape exorcism)
Blocks: 14532
I've just dumped all the most current Netscape documentation into mozilla and
done some minimal sanitizing. This document describes a bunch of stuff that
remains to be done:

http://www.vorstrasse91.com/moztips/mozilla_documentation.htm

I will note which parts of this I can try and take on myself here, and maybe
others can chip in on other parts. 
Ian: I have updated the webpage which holds the checklist for this bug, to
illustrate the items which you have fixed(based on your newsgroup post), and
those which have not been fixed yet.
http://www.vorstrasse91.com/moztips/mozilla_documentation.htm
Just checked in the things I said I would update a while ago from Jayesh's list. 
Adding said list to URL. Working on the next few items.
Hello Ian and other Mozilla Documentation gurus,

I have added a second document with my feedback on "sanitizing" Netscape
references from Mozilla's help sections. There also are other "non-sanitizing"
items in this checklist, although I am not sure which bug(s) they belong too.

http://www.vorstrasse91.com/moztips/mozilla_documentation2.htm

- Jay
Hello,

I think this is where the Mozilla 1.0 RC1 help files in CVS (lxr) can be found:
http://lxr.mozilla.org/mozilla1.0/source/extensions/help/resources/locale/en-US/

- Jay
Hello,

I don't know if all of the information listed in this new page belongs here, but
some it is related to "sanitizing" Netscape references. It also has lots of
"missing information" filled in, such as help on Tabbed Browsing. I wonder which
bug that information belongs to. Anyway, here's the link: 
http://www.vorstrasse91.com/moztips/mozilla_documentation3.htm
- Jay
Hi,

I'm interested in helping with the mozilla documentation, but I don't really
know where to start. Jay's documents go into what's needed pretty well as far as
I can tell, and the links to the CVS repository are helpful, but is there a
document somewhere that talks about operational details like checkins, etc? Is
the system for documentation any different than for code? Are reviews required?
Is there somewhere else I should be asking this question?
Eric, thanks for your interest and offer of help.

Mozilla documentation includes much more than help (developer docs, in the
traditional sense, and informational docs at mozilla.org). At the moment, there
is no single benevolent (or otherwise) dictator for the overall doc effort. I
suggest reviewing recent postings in the documentation newsgroup to give you a
sense of the situation.

As for end-user docs: Netscape currently "controls" the help in the builds, in
that staff writers create content, which we then periodically contribute to the
Mozilla tree. The content needs to be cleaned up for Mozilla---not only does
"Netscape" need to be removed, but the content needs to be tweaked to
accommodate the nuances of differences between Moz and NS (in some cases, the
differences are greater than "nuances"). This isn't a good situation, but I
don't see it changing until Netscape 7.0 is out the door. Thereafter, perhaps we
can use XHTML or XML entities within the help, and then we can check into the
Moz tree routinely, but content relevant for Moz only would appear, thanks to
the tagging.

For now, you might want to consider an end-user help topic that you could post
as an article on mozilla.org, or post a message in the newsgroup and ask what
sort of docs are needed on the developer side.
Depends on: 129566
Depends on: 187378
No longer depends on: 129566
*** Bug 54561 has been marked as a duplicate of this bug. ***
Blocks: 54561
Depends on: 187385, 187387
Depends on: 170108
Depends on: 187425
No longer depends on: 187387
Depends on: 187430
Depends on: 187431
No longer depends on: 187431
bug 54561 dependency tree re-organization. sorry for the spams...
No longer blocks: 14532
Depends on: 89898
Keywords: meta
QA Contact: rudman → stolenclover
Summary: Sanitizing Netscape's documentation for Mozilla users. → Mozilla online help contents tracking bug
Whiteboard: was "Sanitizing Netscape's documentation for Mozilla users"
Depends on: 112271
Depends on: 139810
Blocks: 95770
Is anybody currently working on updating any help files?  If not, I am working
on an overhaul.  I plan to do the overhaul in two primary steps.  The first is
to update existing content.  The second is to add missing content.  I've
contacted Ian Oeschger about it as well as some problems in the "support files"
like the style sheet and JavaScript.
Brant, yes, we (=Netscape) are going to make a big drop into the Moz tree soon,
with updated content (at least, current with Moz 1.2). That should be within a
couple of weeks. I'll have a better handle on the schedule midweek next week.
You might want to hold off until then with any other updates. 
Depends on: 187558
Depends on: 155820
Depends on: 111484
*** Bug 162559 has been marked as a duplicate of this bug. ***
rudman, oeschger: I just saw a dump into the tree.  Is there more coming or is
that it?
Brant---Ian updated all of the files. The deed is done.

This bug is outlasting its usefulness. I'd like to close it to get it off the radar.
rudman, fine with me as long as all the dependent bugs are resolved as well.  I
did notify Ian of a regression due to the update, but I think he fixed it.
*** Bug 77629 has been marked as a duplicate of this bug. ***
No longer depends on: 170108
*** Bug 200191 has been marked as a duplicate of this bug. ***
Depends on: 198000
Depends on: 196656, 196658
Depends on: 206553
Depends on: 210335
taking over some of Rudman's bugs
Assignee: rudman → stolenclover
Status: REOPENED → NEW
Depends on: 220395
Depends on: 226911
Depends on: 232066
Depends on: 235988
Depends on: 235989
Depends on: 236060
Depends on: 240695
As per comment 49 closing this bug.
Status: NEW → RESOLVED
Closed: 19 years ago11 years ago
Resolution: --- → FIXED
You need to log in before you can comment on or make changes to this bug.