Fedora user documentation should fulfill several criteria or (soft) requirements:
As a suggestion, one or more of the following sections (short, 1-3 sentences may be sufficient:
Each documentation should name the author(s) or author team in the header, the Fedora version and the last update date: e.g.
= <TITLE> AUTHOR1, AUTHOR2, ... :revnumber: F37,F38,F39,rawhide :revdate: 2023-12-19 <empty line>
An example that is not yet ideal either: Server VM Install In regard to the current installation text, you should briefly explain in 1-2 sentences what happens (installing on top of MacOS, in VM, dual boot ....) and, if necessary / possible, add a direct link to the corresponding passage in the upstream documentation.
Even a newcomer should be able to decide on this basis whether this is something for them or not.
A link to an external installation script requires a brief explanation of what the installation script does, what changes it makes and, above all, whether and how it can be undone.
That's just said on the fly. I'm using a Mac as my main desktop and have taken note of the project, but nothing more yet. Anyway, I'm interested and would also like to offer help with the documentation.
An unconditioned external hosted installation link is basically a no-go in Fedora documentation. It needs speciific information why it is trustworthy and safe. Better alternatice is to copy it as an attachment to the installation guide (and to update it manually after a security review).
On the last point: the installation script downloads the rest of the installer bundle off of our (Asahi) infra, it is not self-contained. The images themselves are hosted on AWS and also built outside of Fedora infra right now too. Moving all of that into Fedora infra including the builds is not impossible, but as this is all bespoke, it would require significant collaboration. It's not something we can just package up and ask for security review on.
If this is a showstopper for Fedora docs, then maybe we should punt on this whole Fedora docs thing and just throw stuff on our GitHub wiki for now. :/
Nah, we just need to document what's going on and why. Fedora Asahi Remix is a bit weird compared to most Fedora efforts, so this is just some growing pains for everyone involved. :)
I've put up https://pagure.io/fedora-asahi/docs-site/pull-request/3 to try and document this.
Sorry for the late reply, somehow the notification didn't work.
Even though we adhere very strictly to our Fedora principles, this is not a show stopper in my eyes. As @ngompa said, it is a matter of documentation. As things stand today, the most urgently needed information is what modifications the installation makes to the Mac - or a link to the upstream documentation where this is explained (I haven't found anything on this, but perhaps I haven't searched hard enough)..
Log in to comment on this ticket.