449004 - SeaMonkey Website Install Documentation Needs Updating

Status: RESOLVED FIXED

(SeaMonkey :: Website, enhancement)

Description

[Philip Chee]

Originally reported in Mozillazine by R.N. Folsom: <http://forums.mozillazine.org/viewtopic.php?p=4056475#p4056475>

Although I'm not a developer, I have some SeaMonkey website install documentation suggestions, that might assist new potential SeaMonkey users to migrate to (or at least try out) SeaMonkey.

On Release Notes page http://www.seamonkey-project.org/releases/seamonkey1.1.11/, the heading is SeaMonkey 1.1.11. The main page (not the menu column on the left) contains an "End User Documentation" link, with a sub-link, "Before you install," and two sub-sub-links: "If another Mozilla is installed" (which on the target page becomes "If you have a previous version of Mozilla installed"), and "If Netscape 6/7 is installed."

Clicking on "End User Documentation" takes you to "Getting Started with Mozilla [Suite] 1.7.13," which by its title obviously is outdated for installing SeaMonkey.

But if an impatient new SeaMonkey user clicks directly on the sub-link "Before you install," he goes part way down the "Getting Started with Mozilla [Suite] 1.7.13" page, without seeing its heading or any other clue that some of its information is out of date for installing SeaMonkey. (Since SeaMonkey gets some support from the Mozilla Corporation/Foundation, it may not be obvious to a new user that in the "Before you install" sections, "Mozilla" refers specifically to the Mozilla Suite and not to any Mozilla "sponsored" programs including SeaMonkey.)

My suggestions are as follows:

1) Page http://www.seamonkey-project.org/releases/seamonkey1.1.11/
should link to the historical reference "Getting Started with Mozilla [Suite] 1.7.13" only once, with the link title explicitly using that name. I suggest placing the "Getting Started with Mozilla [Suite] 1.7.13" link in the left menu column, immediately below "Documentation & Help."
Alternatively, perhaps the "Getting Started with Mozilla [Suite] 1.7.13" link should be ON the "Documentation & Help" page
http://www.seamonkey-project.org/doc/,
which does correctly note that older documentation can be useful.

Also, the relevance to SeaMonkey of the "Getting Started with Mozilla [Suite] 1.7.13" page might be more apparent, if the page included an introductory sentence with the history that Mozilla Suite 1.7.13 was the Mozilla Suite's last Official Release version, and preceded Mozilla Suite 1.8-Alpha (or was it Beta?), which was the foundation on which SeaMonkey 1.0 was built.

2) On page http://www.seamonkey-project.org/releases/seamonkey1.1.11/
I suggest that the "End User Documentation" link be renamed to "Before you install" (along with its two sub-sub-links and their content), and should go to a new page explicitly designed for SeaMonkey. Most of its content can be based on updated versions of the corresponding sections of "Getting Started with Mozilla [Suite] 1.7.13."

In my opinion, it's especially important that the new "Before you install" page explicitly distinguishes SeaMonkey from its Mozilla Suite predecessors. That's why I've inserted "[Suite]" at various places above.

3) Into the new SeaMonkey "Before you install" page, I would insert a new initial paragraph, recommending (as a rarely needed precaution) that the current user profile or profiles --- whether for SeaMonkey, Mozilla Suite 1.7.13 or earlier, Netscape [8?]/7/6, or Netscape Communicator --- be backed up, either by copying it to a different location, or by using a backup utility.

Then I would continue with two paragraphs based on the current opening two paragraphs of the "Getting Started with Mozilla [Suite] 1.7.13," "Before you install."

I think that the second of these two paragraphs can be used almost "as is," except that its opening sentence should begin "To avoid incompatibility problems with previous SeaMonkey versions, the SeaMonkey installer . . ."

But in my opinion, the first of these two paragraphs needs some real editing. I've split it into two paragraphs here, and I suggest that it read something like the following:

"You can safely install SeaMonkey while retaining other Internet Client software, such as Firefox, Thunderbird, Mozilla Suite 1.7.13 or earlier, Netscape [8?]/7/6, or Netscape Communicator --- although the last three no longer get security fixes, and may not work well with modern websites.
Similarly, you can safely install SeaMonkey while retaining Microsoft Internet Explorer, Microsoft Outlook or Outlook Express, and Opera.

"SeaMonkey can import user data from other Internet clients. However, import may not work if you uninstalled the client first. If you wish to migrate from another Internet client to SeaMonkey, we recommend that you uninstall the client after you have both installed SeaMonkey and have migrated your user data. For more details, read "Migrating from another Internet client".

Of course, the "Migrating from another Internet Client" target page needs to be updated to make it accurate for SeaMonkey, rather than for the Mozilla Suite.

4) Next, I would replace the "If you have a previous version of Mozilla installed" by a new section, titled "If you have a previous SeaMonkey version already installed." It would say something like the following:

"a) If the SeaMonkey version already installed is version 1.1.x or later, the new SeaMonkey installer now automatically uninstalls the old version before installing the new version, so the old version need not be uninstalled manually before installing the new version. That is, the new version can be installed "over" the previous version.

"b) However, if the SeaMonkey version already installed is 1.0.x , then it should be uninstalled manually (in Windows, using Add/Remove programs) before installing the new SeaMonkey version."

[I'm basing suggested paragraphs a) and b) on my understanding of a statement by BenoitRen, the second message in thread "Installing SeaMonkey 1.1.8" at http://forums.mozillazine.org/viewtopic.php?f=40&t=627280 .
However, in that same thread, in the fourth message, BenoitRen says that although for SeaMonkey 1.1.x the full installer (i.e. downloading and then installing the SeaMonkey 12,716kb file) uninstalls the old version, he doesn't know whether the much smaller "stub" installer does likewise.]

I don't know how to revise "Getting Started with Mozilla [Suite] 1.7.13," section "If you have a previous version of Mozilla installed," to make it relevant to SeaMonkey. If someone is trying to migrate to SeaMonkey from Mozilla Suite 1.7.13 or earlier, then this section's implicit advice to uninstall a previous Mozilla Suite before upgrading to SeaMonkey is contradicted by the "Before you install" migration advice NOT to uninstall the old Internet Client (in this case, the Mozilla Suite) until after SeaMonkey has been installed and user data has been migrated.

So I've made a crude attempt to include upgrading to SeaMonkey from the Mozilla Suite into my next recommendation, 5). It undoubtedly needs major revision, by someone much more knowledgeable than I am.

5) The "If you have Netscape 6 or 7 installed" sub-link title perhaps should be updated to "If you have Firefox, Thunderbird, Mozilla Suite 1.7.13 or earlier, Netscape [8?]/7/6, or Netscape Communicator installed." And I think the remainder of the section probably should read something like the following:

"Do NOT share profiles between SeaMonkey and any of these other Mozilla Suite or Netscape programs. By default, SeaMonkey and these other programs share the same profile registry and directory [whatever that may mean]. SeaMonkey automatically uses your old Mozilla Suite or Netscape profile unless you have multiple profiles, in which case SeaMonkey prompts you to choose a profile. [Is this paragraph still accurate for SeaMonkey 1.1.x?]

"However, a profile created (or modified) by any of these programs may be incompatible with a profile created or modified by another of these programs. To avoid accidentally opening SeaMonkey with your old Mozilla Suite or Netscape profile, create a new, extra profile using your OLD Mozilla Suite or Netscape Profile Manager, before installing SeaMonkey. [Then when you install SeaMonkey, it will use that new, extra profile location???]"

[Incidentally, isn't there a better way to isolate --- for example, in an entirely different folder --- the new SeaMonkey profile from the old Mozilla Suite or Netscape profile?]

"Remember the advice at the beginning of this document, that when migrating user data to SeaMonkey from a different Internet Client, do not uninstall the different Internet Client until after installing SeaMonkey and completing the data migration."

In my opinion, the remaining material in "Getting Started with Mozilla [Suite] 1.7.13," beginning with "System recommendation," is not useful for installing SeaMonkey, because it is superseded by the Release Notes Installation Instructions, at http://www.seamonkey-project.org/releases/seamonkey1.1.11/installation
So at the end of the new SeaMonkey-specific "Before you install" document described in my suggestion 2) above, there needs to be a link to these Release Notes Installation Instructions.

I know that these suggestions are imperfect, but I'm hoping that they may encourage and perhaps help someone to clarify and improve SeaMonkey's website install information.

Cordially, Roger Folsom

Comment 1

[Jens Hatlak (:InvisibleSmiley)]

Just commenting on a couple of things that caught my eyes:

(In reply to comment #0)
> 3) Into the new SeaMonkey "Before you install" page, I would insert a new
> initial paragraph, recommending (as a rarely needed precaution) that the
> current user profile or profiles --- whether for SeaMonkey, Mozilla Suite
> 1.7.13 or earlier, Netscape [8?]/7/6, or Netscape Communicator --- be backed
> up, either by copying it to a different location, or by using a backup utility.

That's basically a good advice but it introduces the problem of having to explain how to do a backup of a profile, or better how to find the profile. Maybe <http://seamonkey.ilias.ca/profilefaq/> would be a good starting point here. Of course one can backup the whole hard disk, but I'm not too confident that the average user will actually do that "just to install an application".

> "You can safely install SeaMonkey while retaining other Internet Client
> software, such as Firefox, Thunderbird, Mozilla Suite 1.7.13 or earlier,
> Netscape [8?]/7/6, or Netscape Communicator --- although the last three no
> longer get security fixes, and may not work well with modern websites.
> Similarly, you can safely install SeaMonkey while retaining Microsoft Internet
> Explorer, Microsoft Outlook or Outlook Express, and Opera.

For the Mozilla suite and Netscape 6/7 (Netscape 8 is little more than a re-branded Firefox) that reads to me like you can safely run them side-by-side with SeaMonkey, which is generally not the case. SeaMonkey picks up the profiles of the above mentioned applications, converts/adapts them once to its own needs and then continues using them. The old applications will also use the very same profile when they are started again. Of course one can create new profiles before or after installing SeaMonkey (see below) but that requires manual intervention, i.e. it's not what the average user will do.

> I don't know how to revise "Getting Started with Mozilla [Suite] 1.7.13,"
> section "If you have a previous version of Mozilla installed," to make it
> relevant to SeaMonkey. If someone is trying to migrate to SeaMonkey from
> Mozilla Suite 1.7.13 or earlier, then this section's implicit advice to
> uninstall a previous Mozilla Suite before upgrading to SeaMonkey is
> contradicted by the "Before you install" migration advice NOT to uninstall the
> old Internet Client (in this case, the Mozilla Suite) until after SeaMonkey has
> been installed and user data has been migrated.

On the other hand, the practice of uninstalling the Mozilla suite before installing SeaMonkey has the advantage of minimizing the chance that the to-be-converted profile will be reused with the Mozilla suite (because it requires actively reinstalling the Mozilla suite).

> "Do NOT share profiles between SeaMonkey and any of these other Mozilla Suite
> or Netscape programs. By default, SeaMonkey and these other programs share the
> same profile registry and directory [whatever that may mean]. SeaMonkey
> automatically uses your old Mozilla Suite or Netscape profile unless you have
> multiple profiles, in which case SeaMonkey prompts you to choose a profile. [Is
> this paragraph still accurate for SeaMonkey 1.1.x?]

It's still correct, yes, and it won't change until SeaMonkey 2 is released (which will actually migrate, read: copy data from any previous profiles). Until then it cannot be stressed enough that profile sharing is evil. Even more, when migrating from the Mozilla suite you should note that certain left-overs like /path/to/profile/chrome/overlayinfo/ can and will lead to problems when installing or upgrading extensions.

> "However, a profile created (or modified) by any of these programs may be
> incompatible with a profile created or modified by another of these programs.
> To avoid accidentally opening SeaMonkey with your old Mozilla Suite or Netscape
> profile, create a new, extra profile using your OLD Mozilla Suite or Netscape
> Profile Manager, before installing SeaMonkey. [Then when you install SeaMonkey,
> it will use that new, extra profile location???]"

Not directly, but it will present the Profile Manager and allow you to choose which profile to use, which enables you to leave the old profile alone (and working with the old application).

> [Incidentally, isn't there a better way to isolate --- for example, in an
> entirely different folder --- the new SeaMonkey profile from the old Mozilla
> Suite or Netscape profile?]

There are certain command line switches that allow to either show the Profile Manager, create a new profile or use a certain one but I guess it's unlikely that any of the above will be implemented into the SeaMonkey installer as default behavior for the 1.1.x release branch...

Just my 2c...

Comment 2

[Chris Ilias [:cilias]]

IMO, it's best not to fiddle with the Mozilla Suite docs, and just create new SeaMonkey specific ones, hosted on seamonkey-project.org. The feeling I get is that the real issue is manpower; and that's why the MAS docs are being used. If that's the case, anyone want to volunteer to write it?

Comment 3

[Robert Kaiser]

The "end user documentation" stuff should be completely reworked and move over from www.m.o to our site - something needs to actually do that though and care that everything is adapted for SeaMonkey.

Please split off specific issues as specific bugs though, it's too hard for someone like me to grasp what the core of the message is here.

A bug report should say "That's the problem" with as few words as possible to describe everything needed to understand the problem, and ideally offer a solution that's easy to grasp as well.

Comment 4

[Robert Kaiser]

I restructured the 1.1.13 release notes as found on http://www.seamonkey-project.org/releases/seamonkey1.1.13/ to include the interesting content from the old Mozilla 1.x page linked in previous versions, I hope this fixes the bug report here.
We still need to copy that change to older, archived relnote versions and look into how much of other 1.x end user docs we should port over to the SeaMonkey pages in some way, but I hope the most important step is done now.