How can we improve our documentation?

How can we make the documentation more usable? Are there some features that still aren’t clearly explained? Would another format or medium be easier to understand? Let us know!

You could write more “how-to” guides that describe step-by-step procedures when they are significantly different from, say, Debian/Ubuntu/Mint Linux. For example:

  • I was never able to build ffmpeg until I found a how-to guide on the ffmpeg website for building under CentOS. (Apparently Clr is also derived from Red Hat Enterprise Linux?)

  • I have a 4-button Kensington USB trackball. I would like to map the right rear button to enable/disable drag lock. There are articles available that describe how to write an xorg.conf file to do the job…under Ubuntu. I tried following the instructions, but Clr seems to ignore my xorg.conf file.

When I look on the 'net for how to do something under Linux, I frequently see warnings about the locations where the system expects to find specific files often depends on which Linux distribution is being used. Perhaps Clr does not look for xorg.conf in /etc/X11?

There is a wealth of how-to guides, articles, and posts for popular distributions such as Ubuntu. It seems to me that a knowledge base needs to be developed for Clr if Clr is to gain traction with the user base.

2 Likes

Adding @mvincerra to this conversation. He is our documentation expert! :wink:

And @puneetse and @ttzeng

1 Like

This is a non-obvious thing when I got started too. /etc comes empty but many tools will look there first. For example in Ubuntu system services are in /etc/systemd/system. The things that come from the distro are in same place you do your modifications.

In Clear these are in /usr/lib/systemd/system. So at first I would just make my changes there, but in hindsight I was giving up a good feature. Now what I do is keep everything outside of /etc and /home stock, this let’s me separate what “belongs” to the distro and being managed by that, and the changes I’ve done.

So in a the distro’s stock config and my config are forced apart, IMO this is is a great feature (especially when it comes to automation!), it’s just nonobvious because /etc comes empty. As a bonus if you ever mess something up or want to start from scratch you can safely blow away /etc and the system will effectively return to a default state.

So, in your case you’d make a /etc/X11/xorg.conf.d/blah.conf and the system will use that config. I’m not sure if “inherit” is the right word for this?

1 Like

It is stateless feature from Clear Linux

Please read “man stateless” for an introduction.

Also you can read:

You can find more info at

https://clearlinux.org/search?search=stateless

1 Like

Thank you @castrojo and @miguelinux for your replies. So, I think I get it: system defaults are either hard-coded into the software or stored in config files in system directories, while /var and /etc are for user customization. But that really begs the question: what subdirectory (if any) under /etc/ or /var/ does a particular (customized) config file go?

As per my second example in my initial post above, I am interested in (re)mapping one of my trackball buttons. As I mentioned in my example, I followed what I read in various articles by placing my customized config file in /etc/X11/xorg.conf…where Clr seemed to ignore it.

OK, so it doesn’t go in a system directory; I get that. But, then, where does it go? (/etc/xorg.conf? /etc/<somewhere-else-entirely>? /var/<something>?) And should it be named xorg.conf, and is it even formatted right?

There is a wealth of information available on the Internet for people who wish to tweak and customize their Linux installations. Some of those instructions also work in Clear, while many others do not. What I was proposing was a knowledge base of articles that describe how to customize specific things in Clear where the procedures for doing so is different from other Linux distributions.

We try to answer some of these common questions with man stateless as Miguel already points out.

One of the nice things about man pages is that they can reference and link other pages and there is a breath of pages about config files. For instance, man xorg.conf will show you exactly where Xorg will look for configuration files. In the same way, you can figure out where to put things like tallow.conf, resolved.conf or sshd_config.

If you are struggling to find out where config files need to be put, please do sudo swupd bundle-add man and use apropos <programbase> (e.g. apropos systemd) to see what manual pages are on your system. You’ll find a wealth of manual pages that would be difficult to replace with forum posts and website documentation, there is just so much there.

1 Like

@ahkok Cool! I think I already have man installed, but I’m glad to know another way to search for pages. Last time I used a Unix-like system, it was man -k [keywords]. Some man pages are more difficult than others, but I will see what I can make of what I find.

BTW, there is a gnome tweak tool available at https://download.gnome.org/sources/gnome-tweak-tool/ that might be worth adding to the desktop bundle…

gnome-tweak-tool is already in the desktop bundle. :slight_smile:

2 Likes

Overall, I am excited about the prospect of an Intel optimized version of Linux with Intel optimized versions of Python 3 and R. I also liked that in addition to instructions for installing the operating system locally on bare metal, there were instructions for VMs, Amazon AWS and Azure (did I miss the Google Compute instructions?).

On the data science side, I was also pleased that that there was a bundle for RStudio (the IDE for R), because I have had trouble with dependencies when attempting to install RStudio on Ubuntu (there is a docker image for RStudio and that may help with the Ubuntu dependencies).

But, I found the Clear Linux “Developer” tab to be huge.
Has there been consideration of breaking out databases into a separate tab?
I think I was on page 26 of “Developer” before I saw MariaDB,
I didn’t see MySQL (did I overlook it? – but you do have Wordpress and the Wordpress LAMP stack requires MySQL) and then I saw PostgreSQL.
I clicked to see the details of the PostgreSQL link and I wasn’t sure what was included:
so I looked at the GitHub and I could not tell if it was some sort of include statement or was simply a stub (to be completed later). I am more used to Ubuntu than Red Hat, so a Red Hat user may have found it to be clearer (bad pun) than I did.

I was specifically trying to check whether the native Linux Clear PostgreSQL bundle included the PostGIS extension which is used in mapping/GIS/spatial applications.

If worse came to worse, I could just run the PostgreSQL docker image.

I also noticed that there was a bundle for the Atom text editor :slight_smile:

How would one get Slack desktop?

So, it looks like Clear Linux would handle most, if not all of my use cases, and I would not be stranded without a critical tool and would have Intel optimized versions of Linux, Python 3 and R.

The only downside is I would lose the comfort of working in the Debian/Ubuntu world that I am just beginning to get used to.

Originally we just had one bundle that provided Mariadb and Postgresql, which really wasn’t very useful. Since then we’ve fixed this and made these all into separate bundles.

You need to know that mysql is entirely compatible with mariadb and most of the Open Source community is preferring to use the latter. It works pretty much exactly the same, listens on the same port, etc…

The Postgresql bundle contains just the DB server, no external extensions are included. Looking at PostGIS, I don’t see them supporting our current PostgreSQL version (9.6.x) so this may be a significant issue.

Because slack is proprietary, your best bet is to use flatpak install flathub com.slack.Slack, or install it manually.

1 Like

Highlight columnar storage on disk and in RAM.
Intel’s optimizations involve vectorized computations and columnar storage complements vectorized computations by helping with the I/O bottleneck that occurs prior to vectorized computations. See for example the Apache Arrow and Apache Parquet projects as described in this opinion piece:

Apache Arrow Project

Here is Wes Mckinney’s (author of Python Pandas package) report on the latest update to
Apache Arrow,“Ursa Labs March 2019 Report”:
“The first quarter of 2019 has now wrapped up. In March we spent a good amount of time focused on getting the 0.13.0 Apache Arrow release out of the door. I will mention a few development highlights from the month and provide the full changelog of patches later in the post.”

In addition to working on the Apache Arrow data format; Wes Mckinney / Ursa Labs is also working on an execution engine (which should be of interest to Intel):
" We propose to develop portable, embeddable computation engine in C++ with the following features:

  • Core system ships as portable C or C++ shared libraries, with bindings for each host language (Python, R, etc.)
  • Runtime in-memory format is Arrow columnar format, and auxiliary data structures that can be described by composing Arrow data structures
  • Reusable operator “kernel” library containing functions utilizing Arrow format as input and output. This includes pandas-style array functions as well as SQL-style relational operations (joins, aggregations, etc.)
  • Multithreaded graph dataflow-based execution engine for efficient evaluation of lazy data frame expressions created in the host language
  • Subgraph compilation using LLVM; optimize commonly operator patterns
  • Support for user-defined operators and function kernels

Initially, development will focus on efficient computing on a single node. We would be interested in developing a distributed runtime in the future."
http://ursalabs.org/tech/

If Intel wants to continue to stay relevant in the Python / R data science stack it might want to look closely at Apache Arrow and consider offering support to the development efforts.

On the columnar database front there is the historic C-Store, the proprietary Vertica and the freemium GreenPlum, open source MariaDB as well as AWS Redshift and Google BigTable.
https://greenplum.org/

@Jim_Callahan is this more for Intel, or for Clear Linux? Perhaps this should be a separate thread - it’s getting a bit off topic?

I think there’s two parts to this topic.

  1. Having high quality documentation.
  2. Getting people to read/refer to it (my experience suggests this is actually the harder part).

My experience was that people coming from other distributions are less likely to read your documentation, preferring google or how they did it on their previous distro. When something is different, they want to know why (and when you have good documentation, it’s easy to refer them to it). I can’t tell you how many people had installation issues due to not reading the instructions right next to the download link (nor would they refer to them when they had issues)!

People new to Linux usually have a much easier time and are more likely to use the distro’s resources to learn how things work.

The question I pose is, how do you get people to find/refer to the documentation before jumping on IRC/forum and being directed to it (the holy grail of documentation). It is a problem I have thought about, but made little headway.

@Nirgendsdorf, I appreciate this feedback. One guide we’re considering is a cross-reference comparison of Clear Linux vs. Other Linux distros regarding how to customize your distro with an empty /etc/ and stateless design. While this is not always the case, oftentimes we recommend that users to copy the defaults from usr/share/defaults/... like this example for Apache Spark:
sudo cp /usr/share/defaults/spark/* /etc/spark

https://clearlinux.org/documentation/clear-linux/tutorials/spark

You’ll find this method allows you complete flexibility (part of the benefit of statelessness at the start), while also keeping the usr/share/defaults unchanged–in case of issues in the future.

You’ll see this same approach in other tutorials:
https://clearlinux.org/documentation/clear-linux/tutorials/hadoop
https://clearlinux.org/documentation/clear-linux/tutorials/web-server-install

If you think a comparison of this kind is worth a new document, let us know with a like or comment.
Otherwise, I defer to the recommendation from @ahkok.