hakuna-m/wubiuefi

Documentation is poor / not newbie-friendly

Opened this issue · 1 comments

jerkstorecaller commented

Wubi was relevant because it let beginners use Ubuntu without having to understand advanced concepts (like disk partitioning). This project fails in doing the same.

I ran the installer, it seems to have created the files on my drive, but when I reboot, it just goes into Windows 10 as usual. I don't have errors, I don't have dialogs, no indication that Wubiuefi was ever here, other than the presence of wubildr and ubuntu on my D drive where I installed it.

I'm not looking for help on this issue, I already moved on to using WSL since that's the fastest solution to my immediate needs. I just wanted to say that if I, as an above-average technical user (relative to the average user that might want to use wubi, such as students and academics), couldn't get it to work, and has no idea why, what hope do they have?

I think the issue might be UEFI/Secure Boot related, but really I don't know.

Here's what the wiki has to say about UEFI: "Newer Windows systems are installed in UEFI mode by default." and it mentions an error message. People without that error message have no idea if this applies to them. (Also, "newer Windows systems?" Was this written in 2012? It's every single non-toy PC made in recent years. Literally every college student interested in wubiuefi is going to have this issue.)

Then there's SecureBoot. The documentation goes into confusing technical explanations about grub and MOK the average user shouldn't know or care about.

My advice:

  • Write step-by-step instructions of how to use wubiuefi, and put it front and center. It's more important than anything else in this project. Users don't care what shimx64.efi is, just write "do X,Y,Z to use Ubuntu on Windows. If you get A, do B. If nothing happens, do C."
  • Add this sentence to your simplified guide: "If you're a beginner, and the above steps didn't work for you, ask for help on our issues page. If you're desperate, you may want to try WSL from the Windows Store, or a desktop virtualization program such as Virtualbox." This provides beginners with escape routes guaranteed to work, unlike wubi.
  • Move all the technical details (including compilation guide) into a section AFTER the actual simplified usage steps. Put them on a different wiki page ideally, or in a BUILD file.
  • Don't link to the original Wubi docs (a single huge wall of text) and say "this might still apply". Copy-paste what's still relevant into your own doc. wubiuefi should be a self-contained project. What happens if they take down their site tomorrow?

Sorry for the tone, I'm channeling the frustration of the average user. If I didn't care about improving this project I wouldn't created this issue, I already solved my problem after all. It takes someone who masters wubi/uefi/secureboot to write this doc, I'm not that person or I'd do it myself.

hakuna-m commented

First of all, thanks for your suggestions to improve Wubiuefi docs.

But IMHO the most important parts of your suggestions are already on our FAQ site of the wiki.

It seems that you haven't found that site although the main site (with the feature list) contains a link to our FAQ. So maybe, it is necessary to improve the visibility of the link.

I ran the installer, it seems to have created the files on my drive, but when I reboot, it just goes into Windows 10 as usual. I don't have errors, I don't have dialogs, no indication that Wubiuefi was ever here, other than the presence of wubildr and ubuntu on my D drive where I installed it.

If you read the questions from FAQ, which are ordered by the steps of installation, you should find the question: Where is my Ubuntu entry in Windows Boot Manager for UEFI ?

Here's what the wiki has to say about UEFI: "Newer Windows systems are installed in UEFI mode by default." and it mentions an error message. People without that error message have no idea if this applies to them. (Also, "newer Windows systems?" Was this written in 2012? It's every single non-toy PC made in recent years.

See

Netherless, the whole wiki contains not all of your advices and there are parts which can and should be improved.
But if we consider the whole wiki, I cannot understand your conclusion that the documentation is poor.

  • 👍1