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).

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.

verified. Ian has been slaving away at it for some time now ;-).

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.

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.

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...

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)

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.

*** Bug 54561 has been marked as a duplicate of this bug. ***

bug 54561 dependency tree re-organization. sorry for the spams...

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.

*** 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. ***

*** Bug 200191 has been marked as a duplicate of this bug. ***

taking over some of Rudman's bugs

As per comment 49 closing this bug.