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! GitHub - clearlinux/clear-linux-documentation: This repository contains the documentation source files for Clear Linux OS.
  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? Issues · clearlinux/clear-linux-documentation · GitHub

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 mariadb | Clear Linux* Project . 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 Software | Clear Linux* Project 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 mariadb | Clear Linux* Project, 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: How To Install Linux, Apache, MariaDB, PHP (LAMP) stack on Debian 10 | DigitalOcean

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.

2 Likes

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)

I recognize CL Engineering still has some work to do on firmware-update bundle. I see your thread on this topic here: How to update system firmware

Just to be clear, and for future reference, you should install only firmware-update, and not fwupdates, as stated above.

1 Like

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 :wink:

2 Likes

Happy Hallow’s Eve. If you still need to get credit for Hacktoberfest on GitHub, take some tasty treats from our Clear Linux Docs GH Issues. Check out issues with the hacktoberfest label and submit a PR. It’s so easy, it’s scarrrry!

1 Like

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.

2 Likes

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

Updated packages:
     R-BMA                               3.18.11-1       -> 3.18.12-2

for instance.