[Solved] Installation instructions for Mac could be improved

[macuser33]

On the "[Tutorial] Mac FAQ" Forum page (viewtopic.php?f=74&t=89283), the instructions in A03 are not as clear as they could be.

I suggest the following changes:

1. Change "After verifying the file, the Mac will display a screen which shows OpenOffice.app, then an arrow, then an Applications folder."
to "After verifying the file, the Mac will display a WINDOW THAT shows OpenOffice.app, THEN an arrow, AND an Applications folder."
(bold & uppercase used here only to highlight the changes)

2. Change "Drag the OpenOffice.app icon on that screen into the Applications folder icon on that screen."
to "Drag the OpenOffice.app icon IN that WINDOW ONTO the Applications folder icon IN that WINDOW."
(bold & uppercase used here only to highlight the changes)

The current use of the word "screen" caused at least one person to think they were supposed to drag the "OpenOffice" icon on the desktop to the Applications folder (yes, even though the icon name is different!). That is, people think of the desktop as the "screen". Yes, if one reads all the words in the instructions carefully, they should be able to do the right thing, but why not make it more clear?

Also, the instructions state "Use File → Eject "OpenOffice" (the dmg file)." First, it might not be clear that the user must first click on the "OpenOffice" desktop icon. Second, that operation has nothing to do with "the dmg file"--it's operating on the virtual disk that was created from the dmg file. I would change that sentence to the following:

"Click on the desktop 'OpenOffice' icon, and then use File → Eject 'OpenOffice' to eject that virtual disk." (with double quotes to be used in the actual text).

Or you could simply state "Drag the desktop 'OpenOffice' icon to the Trash to eject that virtual disk." (again, with double quotes; although people might be hesitant to "put" it in the Trash).

By the way, the text for answer A03 is a very long, dense, complicated paragraph. Breaking it down to a bulleted list (i.e., as is done in several other answers) would make the process easier to follow.

On a related note, but in a different context, the page at https://www.openoffice.org/porting/mac/ ... g/ooo.html (which is linked from the general Installation Instructions page) is out of date and incorrect. It says to drag "the OpenOffice.org icon" to the Applications folder, and the graphic shows an "OpenOffice.org.app" icon. Both names are incorrect. Also, in two places, the reader is told to "click on" something when they should be told to double-click.

[MrProgrammer]

Thank you for helping to improve the documentation on our forum, macuser33! I will review your recommendations and update the tutorial. It is helpful to receive comments from others since it can be difficult to assess the usability of material one has written. Like everything else here on a user-to-user forum, our tutorial is unofficial, but I hope it is a good addition to the information at https://www.openoffice.org/download/com ... tions.html.

On a related note, but in a different context, the page at https://www.openoffice.org/porting/mac/ ... g/ooo.html … is out of date and incorrect.

I am not part of the OpenOffice project team and can't help with that documentation. I suspect no one else on this forum can either.

[lgusaas]

1. Change "After verifying the file, the Mac will display a screen which shows OpenOffice.app, then an arrow, then an Applications folder."
to "After verifying the file, the Mac will display a WINDOW THAT shows OpenOffice.app, THEN an arrow, AND an Applications folder."
(bold & uppercase used here only to highlight the changes)

2. Change "Drag the OpenOffice.app icon on that screen into the Applications folder icon on that screen."
to "Drag the OpenOffice.app icon IN that WINDOW ONTO the Applications folder icon IN that WINDOW."
(bold & uppercase used here only to highlight the changes)

Would be useful to use screenshots to show the process. I used to include them when people were unable to follow precise instructions

The current use of the word "screen" caused at least one person to think they were supposed to drag the "OpenOffice" icon on the desktop to the Applications folder (yes, even though the icon name is different!).

Actually some people download the "Apache_OpenOffice,,,install_... .dmg" to the desktop and then move that file to the Applications Folder rather than opening it and them moving OpenOffice.app to the Applications folder.

Also, the instructions state "Use File → Eject "OpenOffice" (the dmg file)." First, it might not be clear that the user must first click on the "OpenOffice" desktop icon. Second, that operation has nothing to do with "the dmg file"--it's operating on the virtual disk that was created from the dmg file. I would change that sentence to the following:

"Click on the desktop 'OpenOffice' icon, and then use File → Eject 'OpenOffice' to eject that virtual disk." (with double quotes to be used in the actual text).

The Icon DOES NOT always appear on the desktop. Depends on the Users preference settings in Finder. Better to give the instructions to eject it in Finder

[MrProgrammer]

Would be useful to use screenshots to show the process.

Due to the structure of the tutorial and the limitation of three attachments per post, it is not practical to include images, however I can include links to other posts with the images.

[macuser33]

Actually some people download the "Apache_OpenOffice,,,install_... .dmg" to the desktop and then move that file to the Applications Folder rather than opening it and them moving OpenOffice.app to the Applications folder.

They might do that, but it achieves nothing useful. The dmg file must eventually be opened in order to get to the OpenOffice window that contains the OpenOffice application. Why even mention that obscure possibility? Clearly written instructions would not give anyone the idea of doing that.

The Icon DOES NOT always appear on the desktop. Depends on the Users preference settings in Finder. Better to give the instructions to eject it in Finder

I had not thought of that complication. In order to eject the OpenOffice volume "in the Finder", the user will need to find the icon. If they have the Finder configured to not display external disks on the desktop, the volume will be at the root level of the Finder's file system. Good luck explaining that! It might be easier to tell them to change the Finder preferences if the icon is not on the desktop.

[lgusaas]

Actually some people download the "Apache_OpenOffice,,,install_... .dmg" to the desktop and then move that file to the Applications Folder rather than opening it and them moving OpenOffice.app to the Applications folder.

They might do that, but it achieves nothing useful. The dmg file must eventually be opened in order to get to the OpenOffice window that contains the OpenOffice application. Why even mention that obscure possibility? Clearly written instructions would not give anyone the idea of doing that.

It is not an obscure possibility. You obviously haven't been answering questions on this forum. I lost count years ago on the number of times someone downloads AOO then moves the install .dmg into the application folder rather than properly installing the .app. Sometimes it was downloaded originally to the desktop. They have never read the help instructions on this site or on the download page.

Even when very clear, explicit instructions are given they fail to follow them.

The Icon DOES NOT always appear on the desktop. Depends on the Users preference settings in Finder. Better to give the instructions to eject it in Finder

I had not thought of that complication. In order to eject the OpenOffice volume "in the Finder", the user will need to find the icon. If they have the Finder configured to not display external disks on the desktop, the volume will be at the root level of the Finder's file system. Good luck explaining that! It might be easier to tell them to change the Finder preferences if the icon is not on the desktop.

Much less likely for it not to be in the Finder's sidebar. If so, they could just delete the install .dmb. Oops! Tried that. The install .dmg was deleted, but it WAS NOT ejected.

[Hagar Delest]

Due to the structure of the tutorial and the limitation of three attachments per post, it is not practical to include images, however I can include links to other posts with the images.

You can break your single post in several posts. Each post can have a different title.
That's what I do especially when it can be split into different sections.
The advantage is also that you can point to a specific part of the tutorial directly. More comfortable than looking for the Q/A number.

[MrProgrammer]

You can break your single post in several posts. Each post can have a different title.

Yes, perhaps I should do that, though it will take a long time since the tutorial covers more than 50 situations. Adding images to the new posts would require even more time. I'm not opposed to rebuilding the tutorial but this may take a month or more before I find the dedication for that, expecially since I have other tutorials in-progress.

[macuser33]

I hope my suggested minor changes to wording will not be delayed by a long-term project to make major revisions to the tutorial.

[MrProgrammer]

1. Change "After verifying the file, the Mac will display a screen which shows OpenOffice.app, then an arrow, then an Applications folder." to "After verifying the file, the Mac will display a WINDOW THAT shows OpenOffice.app, THEN an arrow, AND an Applications folder."

Changed

2. Change "Drag the OpenOffice.app icon on that screen into the Applications folder icon on that screen." to "Drag the OpenOffice.app icon IN that WINDOW ONTO the Applications folder icon IN that WINDOW."

Changed

[Change] "Use File → Eject "OpenOffice" (the dmg file)." to "Click on the desktop 'OpenOffice' icon, and then use File → Eject 'OpenOffice' to eject that virtual disk." (with double quotes to be used in the actual text).

The Icon DOES NOT always appear on the desktop. Depends on the Users preference settings in Finder. Better to give the instructions to eject it in Finder

In order to eject the OpenOffice volume "in the Finder", the user will need to find the icon.

Since "the window" from the first suggested change represents the virtual volume, Finder will offer File → Eject 'OpenOffice' if the window is active, which it should be since the very last operation was the drag inside the window. The user does not need to locate an icon to perform the eject. The tutorial does not need to mention a "virtual disk".

By the way, the text for answer A03 is a very long, dense, complicated paragraph. Breaking it down to a bulleted list (i.e., as is done in several other answers) would make the process easier to follow.

Changed

If so, they could just delete the install .dmg. Oops! Tried that. The install .dmg was deleted, but it WAS NOT ejected.

The next reboot will unmount (eject) the volume.

Even when very clear, explicit instructions are given they fail to follow them.

I have found that to be especially true for Mac users. It seems they don't even read the instructions, much less attempt to follow them. But that's OK. When they have trouble they'll post here and I will respond with, typically, only a link to the tutorial and the relevant Q/A pair, nothing more. Most people eventually get the message that they will need to read the instructions.