Ideas for the Installation page
I've been working on a re-make of the installation guide, featuring separate articles for the pre-built image install and the pmbootstrap install, as well as useful links to other related articles (such as dualbooting, troubleshooting, other install methods, etc.). I'd appreciate some feedback:
https://wiki.postmarketos.org/wiki/User:Knuxfanwin8/Installation_guide_rework
Here's some of the considerations I took in making this page:
- Give both pre-built images and pmbootstrap the same amount of attention - in this case, both are displayed in prominent "boxes", each explaining the merits of each installation method.
- Try to hopefully minimize the likelihood of users skipping over important steps of the process.
- Highlight the importance of reading the device's wiki page.
- Give the user suggestions on what to do after the installation process - see the "Finishing up" section. (The list of examples I gave might still need a bit of changes - this is just an example for what we could add there).
- Mention the troubleshooting pages and the possibility of asking for help in Matrix/IRC.
Still, there are a few other things to consider when it comes to the installation guide...
The role of the "Installation" section on device pages
These new installation pages call back to the "Installation" section of device pages multiple times. The assumption here is that this section (or the wiki page in general) will contain the following information:
- Bootloader unlock, if needed
- Additional prerequisites like lk2nd, if needed
- How to enter the flashing mode (usually in the "How to enter flashing mode" section, but still on the device wiki page)
- Which flashing command should be used, and whether there's any special considerations for running it
These are all different between various devices, so it would be difficult to make a single wiki page that covers them all (especially since this sort of thing would quickly become very tedious to read). But there is a way:
Per-device installation guides
I've seen some folks in the postmarketOS chat suggest a different approach to the installation guide - one where it's generated separately for every device. I see @flamingradian has been working on such a guide for the Pixel 3a and a template for similar guides). That template pretty much entirely covers my own considerations for install guides, and has some other neat ideas (like the Maintenance section) - definitely worth giving a look as well.
LineageOS uses a similar system for their wiki, where each device page is automatically generated and has links to a specially-prepared installation guide (example).
My primary counter-argument against this is that making sure such a guide is available for every device would take quite a bit of effort, given just how many devices there are, but since everything is powered by a template, and since we already store plenty of flashing and installation-related information in deviceinfo files, this could be pretty easily automated. Alternatively, specific install guides could only be added for more popular devices.
Again, I'd love to hear what other folks in the community think.
Considerations for the pmbootstrap page
The pmbootstrap install guide I've proposed duplicates a lot of the content that was moved into the pmbootstrap page.
Personally, I don't think that page itself is the ideal place for an installation guide; there are very different requirements for an installation guide (as seen in my proposed version - there's a Preparations section, and a proper flow focusing only on the installation process, not the other features of pmbootstrap).
In my opinion, the pmbootstrap page should focus primarily on the various development uses of the tool - building packages, exporting images, good practices for working with it (pmbootstrap status
and pmbootstrap pull
, etc), maybe some more advanced install commands - and probably include some kind of explaination of how it works (kind of like I did on the pmbootstrap install guide), to prevent people from thinking they have to install cross-compilation packages on their host system and whatnot.
Developers who want to use pmbootstrap aren't going to the article for installation advice (which currently takes up a large part of it). Folks who are just starting out and want to test pmOS out aren't interested in the development bits.
Still, that's just my opinion, and I might be overthinking it; I'd love to hear what others think about this.
cc @ollieparanoid, since you revamped the Installation/pmbootstrap pages a while back, and I'd feel bad overwriting some of your work without asking :p
See also
For inspiration: