Troubleshooting: expand and update

[grahamperrin]

Add a section for Secure Boot.

Link to STABLE.

For hardware components, direct readers to hardware information that is provided by the FreeBSD Primary Release Engineering Team.

Add two dual-GPU scenarios.

Add a placeholder (ellipsis) subheading for the section that is incomplete.

Whilst here, reword things a little.

Original (draft) Summary by Sourcery

Expand and update the troubleshooting guide by adding Secure Boot information, updating links, and rewording sections for clarity.

Documentation:

• Add information about disabling Secure Boot in BIOS settings for troubleshooting boot issues.
• Update the link to the FreeBSD STABLE branch for hardware support information.
• Include a placeholder for missing desktop environment issues in the troubleshooting guide.
• Reword and clarify sections on hardware support and installation media corruption.

[sourcery-ai]

Reviewer's Guide by Sourcery

This pull request expands and updates the troubleshooting documentation, focusing on Secure Boot, hardware compatibility, and dual-GPU scenarios.

State diagram for boot troubleshooting process

stateDiagram-v2
    [*] --> CheckSecureBoot
    CheckSecureBoot --> DisableSecureBoot: Secure Boot enabled
    DisableSecureBoot --> AttemptBoot
    CheckSecureBoot --> AttemptBoot: Secure Boot disabled
    AttemptBoot --> Success: System boots
    AttemptBoot --> HardwareCheck: Boot fails
    HardwareCheck --> TryDifferentComputer: Hardware suspected
    TryDifferentComputer --> MediaCheck: Fails on different computer
    TryDifferentComputer --> HardwareIssue: Works on different computer
    HardwareCheck --> MediaCheck: Media suspected
    MediaCheck --> DownloadNewISO
    DownloadNewISO --> CreateNewUSB
    CreateNewUSB --> AttemptBoot

Loading

File-Level Changes

Change	Details	Files
Added a section to guide users on disabling Secure Boot if enabled in BIOS settings.	Added information about Secure Boot and its impact on FreeBSD.	source/user/installation-guide/troubleshooting.md
Updated hardware compatibility information to direct users to FreeBSD's official resources.	Replaced a general hardware compatibility link with a dynamic link based on the GhostBSD version. Added instructions on how to determine the FreeBSD version used by GhostBSD.	source/user/installation-guide/troubleshooting.md
Included two common dual-GPU scenarios that may prevent reaching the graphical desktop environment.	Added information about potential issues with NVIDIA Optimus and dual-GPU Macs. Suggested disabling one of the GPUs in BIOS settings if possible.	source/user/installation-guide/troubleshooting.md
Added a placeholder for an incomplete section and updated the outdated ISO image link.	Replaced the outdated ISO image link with the latest image link. Added a placeholder subheading for the incomplete section.	source/user/installation-guide/troubleshooting.md
Improved clarity and wording throughout the troubleshooting guide.	Reworded sections for better clarity and conciseness.	source/user/installation-guide/troubleshooting.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time. You can also use
  this command to specify where the summary should be inserted.

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[grahamperrin]

https://docs.freebsd.org/en/books/faq/#hardware in the rewritten book of FAQ is not a good point of reference.

Re: https://codeberg.org/grahamperrin/freebsd-doc/pulls/21 the first FAQ link for graphics is to https://wiki.freebsd.org/Graphics/Intel-GPU-Matrix, which is explicitly stale with an obsolete table; and so on.

[sourcery-ai]

Hey @grahamperrin - I've reviewed your changes - here's some feedback:

Overall Comments:

• There's a typo in the word 'occasionally' (spelled as 'ocassionally') that appears in the document.

Here's what I looked at during the review

• 🟢 General issues: all looks good
• 🟢 Security: all looks good
• 🟢 Testing: all looks good
• 🟢 Complexity: all looks good
• 🟢 Documentation: all looks good

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[ericbsd]

LGTM

[grahamperrin]

Thanks!

Side notes:

• the motivation for this PR was losing a potential user of GhostBSD (an existing user of Microsoft Windows) in FreeBSD Discord – at the tail end of one conversation, it was suspected that Secure Boot might be the simple explanation for the person metaphorically getting nowhere, after writing to a USB drive more than once
• the need to disable Secure Boot is not yet covered in FreeBSD installation information (e.g. https://github.com/freebsd/freebsd-doc/blob/main/website/archetypes/release/installation.adoc) or the documentation portal, there's discussion in Discord
• for https://ghostbsd-documentation-portal.readthedocs.io/en/latest/user/installation-guide/troubleshooting.html#your-hardware-may-not-be-supported, I was not entirely happy about writing a need for the reader to mentally correlate (e.g. 1401502 and 14.1-STABLE) – IMHO it's not suitably newbie-friendly – but for now, it'll do.