is very important and relies on the community and helped by the ease in finding the information (the harder to find, the less likely people do it).
As an example, with this thread I tried to refer to the documentation. Spent awhile looking at the website, couldn’t find anything, then figured there would be a man page. I could only find this as I’ve used clr-boot-manager for a couple of years, but took a lot longer than if I just answered from memory.
One of my goals when looking at documentation for Solus was to have it in all one place, a one stop shop for help so people would look there first next time. This meant having all the useful stuff on the website (regardless of the quality of man pages or other sources). I’m not sure how successful it was, it likely didn’t cover a broad enough range of topics to become the go to for users (over google).
I think it was less that IRC users didn’t read docs, more than that’s where people ended up for support in many cases (before the forums existed in particular).
Should also preface that my comments/experience are more around traditional desktop users, many of which aren’t developers, which will likely be a smaller but growing segment now with the new installer. I would presume developers to be more inclined to refer to documentation.
Considering how important virtualization is, it might be a good idea to spruce up the how-to guide for installing CL as a guest OS in VirtualBox. The instructions for installing the VirtualBox Guest Additions are incomplete and out-of-date.
Thanks for giving some background, @sunnyflunk. By documentation for Solus, I believe you mean the “Help Center” page, correct? https://getsol.us/help-center/home/ If yes, apart from the nice grid layout with icons, I see each section includes a nice list view (e.g. Configuration). Clear Linux* OS docs is actively engaged in revisiting layout, presentation, and searchability of docs. Keep your eyes open in the coming months for more improvements.
Add more Info pages to the bundles. At least for GNU software, the Info pages are more detailed and updated more frequently than the corresponding man pages (they say so, right on their man pages). Info pages are marked up for hypertext, so they are more accessible than man pages. GNU manuals are available here.
I’d like to see better documentation of bundles, especially where the Clear Linux team takes an opinionated line on what to include. A case in point is https://clearlinux.org/software/bundle/mariadb . I wanted to install mysql. I had no idea that mariadb was an equivalent of sorts, so was very close to the rabbit hole of building mysql myself before I happened to come across a forum post mentioning mariadb.
Ideally I’d like to see more information on bundles from swupd (and at https://clearlinux.org/software which presumably draws on the same metadata?), to be revealed via swupd search. In this case mariadb was listed from swupd search mysql, but I then needed to drill into more info on the bundle. It would be great to have a swupd equivalent of apt show to get more information on a candidate bundle.
Regarding documentation of bundles, I believe you’re asking which bundles/packages are included in the parent bundle. When viewing a bundle in the Software store, click Inside the bundle to view what’s included. In the case of https://clearlinux.org/software/bundle/mariadb, this shows:
Please note: LAMP stack uses a lot of variations for “P”, which could stand for PHP, Python, or Perl.
I realize that may be confusing (it was to me when I first started). Here’s a good breakdown of LAMP.
@mvincerra - thanks. My mariadb example probably wasn’t the best one in that I did ultimately install & use it without any problems.
My main point re the docs is that unless you already know exactly what you’re looking for by name, neither the online bundle docs nor swupd are of much help. Package managers correctly leave detailed information behind links to repos, but a one line description of the purpose of a bundle is always useful.
Sure, I understand the value that apt show provides on Ubuntu. For now, mostly, you do need to know the name of what you’re looking for ( apart from using swupd search for bundle suggestions). As for specifics on package information, version, etc., you may find our DNF repo query guide helpful.
Here’s another example - I installed the fwupdates bundle today to get firmware updates. I’ve since discovered the bundle isn’t yet fully functional. The current status of a bundle would ideally be discoverable either via swupd or the Software section of the web site (rather than the current trial-and-error)
Thanks. And, sure, I understand not every bundle is perfect or complete. CL is a wip, but it’s certainly more than functional enough for my daily use. I’ve become confident enough in its stability to expunge other OSs from my work laptop.
From a documentation point of view, I was pointing out that ideally I would have been able to find out which of the firmware-related bundles to install, and the current readiness of the bundle, from the bundle docs, rather than having to ask on the forums. Again, I understand documentation is also in progress, and is never going to be complete, but this is the how-to-improve-documentation thread
We’re still working on improving search functionality for bundles–especially from the standpoint of the docs. In the meantime, check out the Available bundles page, and search for “firmware”. Take for example, firmware-update, which shows an “Active” status. This page is built automatically upon build of the docs. Check out the date stamp in the upper right of the table. For an explanation of all statuses, see Bundle status.
Personally I feel a big win for newcomers would be to see versions of software packages.
One would think it’s a very basic requirement.
For example if a user visits the canonical page of a package, let’s say for example postgresql at https://clearlinux.org/software/bundle/postgresql there doesn’t seem to be any way to know which version will be installed without googling and hoping it’s mentioned in a forum.
We are working to provide this information in an easier to consume way, unfortunately I don’t have a timeline for external availability (still not yet something we have deployed internally). In the meantime would something like release notes sent to a mailing list be something you would be interested in?
The format we have internally looks like:
Release notes for the update from 32630 to 32640
R-BMA 3.18.11-1 -> 3.18.12-2