How can we improve our documentation?

Your question is: " …how do you get people to find/refer to the documentation before jumping on IRC/forum…" is perennial. It’s one we contemplate daily in documentation.

The best possible answer I can give you is twofold:

  1. Contribute to our docs! https://github.com/clearlinux/clear-linux-documentation
  2. Make reference to our docs wherever you can–even in IRC.

We welcome suggestions and PRs from the community. Whether users choose to read, or ignore the docs, before using IRC, may be better posed as: Why don’t IRC users refer to the docs more?

  1. 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.

Thanks for the feedback , @LionMage. How about giving us detailed feedback on what specifically you’d like improved --a part from general updates --by filing an issue in our repo? https://github.com/clearlinux/clear-linux-documentation/issues

Sure! Just as soon as I figure out how to actually get the job done first, so I can provide all the specifics you want.

I’ll be testing the VirtualBox Guest Additions over the next day.

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.

1 Like

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:

Included bundles
- lib-openssl
- libstdcpp

Included packages
- jemalloc-lib
- mariadb
- mariadb-doc

If, by chance, you’re creating a Python LAMP stack, the “M” often refers to either MySQL or MariaDB. See also: https://www.digitalocean.com/community/tutorials/how-to-install-linux-apache-mariadb-php-lamp-stack-on-debian-10

1 Like

You may be interested in our tutorial Set up a LAMP web server. It uses MariaDB.

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.

1 Like

@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.

1 Like

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)