opencore guide Mac USB installer doc issues and changes

[rndymond]

Open Core Install Guide Creating a USB installer https://dortania.github.io/OpenCore-Install-Guide/installer-guide/mac-install.html#downloading-macos-modern-os

Hello I am finding the documentation for open core is confusing to follow, so I am contributing by re-writing the steps so that they are actually steps.

The documentation has a number of structural problems:

1. Important steps are put in a “note” bullet point instead of being included in the correct part of the procedure.
2. Previous authors are skipping steps and making assumptions about what the readers knows and does not know. The assumption for a manual of this type should be that the users are new and don’t know anything about creating custom OS installs.

I will also be commenting on certain usability issues, such as the browsers blocking cut and paste of text markup with the HTML tags.

Sections between <>>>>>>>> are copied from the guide

SECTION: USB CREATION

<>>>>>>>

For machines that need a specific OS release or can't download from the App Store, you can use the Munki's InstallInstallMacOS utility. In order to run it, just copy and paste the below command in a terminal window:

<>>>>>>

Issues: The HTML formatting used for the command line code has the following issues: The code goes off screen and the chrome browser seemed to fight me on copying it. Also the code formatting choice does not show what has been selected as it does on regular parts of the guide. Since most code in the guide will be copy/paste this is a real flaw in the guide’s formatting. Please change the CSS for the code so that

1. it is very obvious what code (text) has been selected
2. all code (text) to be selected is visible and not hidden.

Current screenshot showing these issues below.

After executing to command line command, the user is then presented with a list of versions of MacOS. The version numbers are useful, however there are duplicate entries. For example there are three (3) versions of MacO Catalina version 10.15.7. They have different build numbers for example 19H15 or 19H2

Issue:

There is no explanation as to which version and build of the operating system a user should choose.

Fix:

The Open core guide needs to be clear about what to do if there are duplicate build versions presented. If there is a problem with the OS version they chose people may have to start over with another 8GB download. If it does not matter what build version they choose as long as it is the correct MacOS version, that is also important information to tell your users at this point.

Setting up the installer section

<>>>>>>>>>>>>

Now we'll be formatting the USB to prep for both the macOS installer and OpenCore. We'll want to use macOS Extended (HFS+) with a GUID partition map. This will create two partitions: the main MyVolume and a second called EFI which is used as a boot partition where your firmware will check for boot files. • Note: By default, Disk Utility only shows partitions – press Cmd/Win+2 to show all devices (alternatively you can press the View button)

<>>>>>>>>>>>>

This section on USB formatting and partition creation is confusing. The section does not articulate the steps clearly and is, well, scatter brained. Process steps should not be in Notes. The steps to take should be in order and clear. Instead this section should be clearly showing the steps to follow, as follows:

Fix:

Formatting and creating the partitions on the USB.

Now we'll be formatting the USB, creating 2 partitions to prepare it for both the macOS installer and OpenCore. Using DiskUtility, choose view all. Then choose the USB drive and select erase. Choose the following Erase (formatting) parameters: Name: MyVolume (important for later) Format: Mac OS Extended (Journaled) Scheme: GUID Partition Map Once complete your USB will have a single partition called MyVolume

Using DiskUtility choose the USB drive and select Partition Choose the + to add another partition with the following parameters Name: EFI (important for later) Format: Mac OS Extended (Journaled) Size: 1 GB note that the EFI partition for the boot loader should not require more than 200 MB so setting it at 1GB should provide ample space.

Once your are done you should have a USB drive that looks like this:

Please note that this graphic shows what the USB should look like at the end.

Please remove the current diskutility screenshot from the guide, it is confusing and shows a bunch of other drives.

Issue:

Create Install media steps are incorrect. This section needs to clearly describe what users should do. It actually gives incorrect instructions

<>>>>>>>>>>>>>

Next run the createinstallmedia command provided by Apple (opens new window) . Note that the command is made for USB's formatted with the name MyVolume:

The command line below this text is copied from Apple, has no explanation and runs off the page.

<>>>>>>>>>>>>

If a user actually follows the instruction “run the createinstallmedia command“ it fails. The documentation literally tells the user to do the wrong thing. Again a key point is in a note instead of being included where it should be in the steps.

Fix:

This section should read:

Next we will create create the installer on the USB drive by running a command specific to your target operating system using a command line program from Apple. Examples of the command line createinstallmedia command can be found for each MacOS version at this Apple Support link: How to create a bootable installer for macOS.

Rather than list the details here, please go to the Apple Support page How to create a bootable installer for macOS and follow the steps under the heading Use the 'createinstallmedia' command in Terminal

[PMheart]

Hello! Sorry for the late response and thanks for your contribution! Please file a new PR if possible; however, we will review this instead if time does not permit.