Ideas for Detailed User Guide #1
Comments
|
|
It's finally on GitHub. I can fork and clone this repo and get my latest additions incorporated. WooHoo! |
|
One key question we need to answer is whether we want the Silverblue docs to reproduce material that's available elsewhere. Personally, I'm unconvinced that we should be maintaining our own installation guide or our own podman docs: it's a lot of material that will inevitably end up being reproduced elsewhere. |
|
I would think the end goal would be something like the RHEL manuals or the Fedora manuals - a comprehensive, searchable HTML / PDF / EPUB technical document that answers every question a user might have, eliminating the need for Google or Stack Overflow during troubleshooting. ;-) Of course, nobody's documentation is that good, but some come closer than others. And it takes time and effort that may not be in anyone's budget except for volunteers. You're right - podman and the installer that has the same name as a popular Python, R and Julia data science stack are documented well elsewhere. But the existence of that naming conflict alone is why one might want to do Silverblue installer documentation within a comprehensive Silverblue manual. P.S.: the Silverblue installer workflow differs from Fedora Workstation. |
|
Where would this be done / hosted? A separate repo, using the wiki feature on this repo, within a sub folder of this repo or somewhere else entirely? Personally, I like the idea of an advanced / additional guide or user manual in general but as touched upon already is it necessary to get into great detail for things that have existing docs. Would it not be best to give an introduction on how to use, for example podman, and for the more specific / technical details, provide a link to that section otherwise when they update docs it will have a knock on effect |
|
The thing is, there is a comprehensive installation guide for Fedora, and I think that 95% of that is correct for Silverblue... Do we really want to maintain our own version of that 95%? The other thing I'm conscious of is that, in many cases, people just need to know 2/3 key pieces of information before they install (what to expect from Silverblue, should you use manual partitioning, is dual boot possible, etc) - those could get lost in a big guide. |
If it's a technical guide I think it's good to make it collaborative; whether that's a section in the docs or a wiki on GitHub, I'm not sure... ...
I quick podman intro could be nice, as a kind of teaser. Something along the lines of a 5 minute hello world tutorial, for example. |
Official Video tutorial would maybe be handy for that - people could follow along on their phone as they install ( is there a vimo or YT channel for Silverblue? ). However not sure if using the wiki if you can embed videos - ran into issues with that previously and can't remeber if we worked it out. Sure we left it as a screenshot linking to the video. |
|
I was originally working on the advanced guide for Silverblue, based
initially upon the work of Micah Abbott. I followed the outline he
created verbatim. Since that initial effort, there has been many
updates to Silverblue (I began with F28), and there has also been
changes to various parts of Fedora's internals ( if you will) in the
form of BLS adoption, some advances in Podman/Buildah/Skopeo, and an
ever evolving Flatpak landscape to name a few. There is an opportunity
to provide a more comprehensive layout of how to do certain things
within Silverblue, that at this time you must search multiple resources
to find the relevant info on. As an example, take flatpaks, I
envisioned the advanced Silverblue guide detailing the various flatpak
options available to a user in order to tweak their favorite app to
their needs, instead of just referring them to the location where
flatpak has the info, also show how to do it with Silverblue. The
ostree (both rpm-ostree and libostree) is another area of detail that
requires searching in at least two other locations to come up with the
necessary info to tackle some of the more advanced tasks. If you go
here https://miabbott.github.io/2019/01/22/silverblue-day-1.html Micah
has already a very good walk through guide for new Silverblue users to
follow and get rapidly up to speed on how to use it and some of what is
capable. As I see it, and this is largely my opinion and open to
change, I didn't mind following the format outlined since it was
familiar to the community, I felt it just needed the be a "closer look"
at the details of doing it with Silverblue.
…On Wed, 2019-05-08 at 03:45 -0700, Allan Day wrote:
The thing is, there is a comprehensive installation guide for Fedora,
and I think that 95% of that is correct for Silverblue... Do we
really want to maintain our own version of that 95%?
The other thing I'm conscious of is that, in many cases, people just
need to know 2/3 key pieces of information before they install (what
to expect from Silverblue, should you use manual partitioning, is
dual boot possible, etc) - those could get lost in a big guide.
—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or mute the thread.
[
{
***@***.***": "http://schema.org",
***@***.***": "EmailMessage",
"potentialAction": {
***@***.***": "ViewAction",
"target": "
#1 (comment)
",
"url": "
#1 (comment)
",
"name": "View Issue"
},
"description": "View this Issue on GitHub",
"publisher": {
***@***.***": "Organization",
"name": "GitHub",
"url": "https://github.com"
}
}
]
|
We definitely have to find the right balance between Fedora + Silverblue docs. I originally set out to have documentation that was wholly contained within the Silverblue space, regardless of what was available in the Fedora docs. However, after toiling on the first portion of the install guide (again, knowing I was reproducing content), I'm not sure that is the right approach. Even more so, since I've not been able to dedicate the time I wanted to improving the documentation. I think the changes that @allanday has made so far definitely make the docs more approachable and easier to use. And I agree with others commenting that we need to give some introductory documentation on how to use tools that are not typical of the Fedora Workstation experience ( I'm still partial to about 75% of the original outline as being good topics to cover; maybe we don't have to get into as much depth as I originally had in mind, but it should be enough to get users moving in the right direction. |
|
Just some feedback from twitter - someone wanting to try out Silverblue but hasn't due to lack of info for installation:
Dazzy |
Maybe we could document the 5% that is different from standard Fedora, and refer to the Install Guide for the rest? |
migrated from https://pagure.io/fedora-docs/silverblue/issue/17
(This idea has bounced around the various places Silverblue has lived; hopefully this is now a permanent home.)
I would like to create a detailed, hands-on/end-to-end guide for the Silverblue docs. It would be much more verbose, with screenshots and terminal examples, that would be geared more towards new users rather than old veterans.
My starts with documenting the install of Silverblue from the very beginning, showing all the steps required to get to that first login screen, and perhaps discussing some of the options along the way.
After that first login, the guide would talk about some of the first steps users will want to do, like enabling the Flathub repo, layering in some packages, perhaps enabling RPM Fusion, maybe turning on SSH logins, etc. It can cover these operations using the CLI and gnome-software.
Then it could delve into using containers to provide tools that aren’t available on the host, including how to use buildah and podman.
My first set of ideas for the guide is outlined below. I’d like to curate and expand on these ideas, so please weigh in!
The first steps towards this guide has already been implemented in the Installation Guide, but there is clearly more we can document.
migrated comments follow
The text was updated successfully, but these errors were encountered: