How can we improve our documentation?

Feedback Documentation
41

That’s great to hear.

Can’t speak for others, though my prefereance would be pull rather than the push style of a mailing list. All of us deal with so many emails and issus everday, that 719 out of the 720 hours in a month things like version numbers are just added noise to regular end users who are not CL devs or closely related parties.

For me it’s most relevant and needed when doing devops/maintenance. So installing a new package or upgrading or whatever. If the information is available when needed that’d make for a happy user.

42

Could you just make a repository for release notes?
In that way I can git clone the repository and use all the tools I’m used to to find information I want.

43

Seems reasonable to me and given @cmilne’s reply more in line with what would be useful for folks (and certainly aligns with how they are used today internally). I’ll see about getting a repo published for this.

2 Likes
44

There are release notes of the style @william.douglas posted on the downloads server if you’re looking for a particular release in the RELEASENOTES and RELEASENOTES-#####-to-##### files

https://download.clearlinux.org/current/

1 Like
45

Clear Linux is supported on the Intel NUC, but looking at the Intel NUC documentation one wouldn’t know it. For example, on this page about updating firmware, I see references to "Window"s and “OS Independent”. I almost feel as if I need to go back to Windows to update the firmware before continuing in Linux.
Are their any Linux or Clear Linux specific tools for dealing with NUC firmware?

46

@puneetse @william.douglas @tvb

crosspost of Clear Linux Project has a new documentation site - #2 by mek in suggestion of @Businux

Looks like this info is quite outdated but also still I stumble over old links which do not work anymore.

for example, if I look at:

It still has an old link:
https://docs.01.org/clearlinux/latest/guides/clear/mixer.html

which has a 304 to:
https://corpredirect.intel.com/Redirector/404Redirector.aspx?404;https://docs.01.org/clearlinux/latest/guides/clear/mixer.html

which hits:
https://www.clearlinux.org/clear-linux-documentation/latest/guides/clear/mixer.html
which does not exits.

Is it possible to strip or redirect the /latest (and maybe other ones similar if exist) on the webserver
Usually the ones without /latest work, like here:
https://www.clearlinux.org/clear-linux-documentation/guides/clear/mixer.html

Maybe not so easy, but looking at the web server logs of docs.01.org / corpredirect.intel.com / www.clearlinux.org could show from where redirects come and which pages fail.

And till then if one hits a 404 documentation link with a /latest as part of the URI
stripping that seems to help. :wink:

1 Like
47

This would be a good question for @djklimes although I suspect he has higher priorities.

Chris

1 Like
48

It would be great if we have the same quality & formats ( and level differenciation ) than openSUSE Documentation

For me Files in pdf format are the best. Off-line pdf or epub allow us to learn in more portable and easy way …

And it is also simplier for new user trying to instal CLR on the best way.

ClearLinux.User.809

49

Easy to print too, same for cheat sheets.

1 Like
50

That 's right :grin:

1 Like
51

As a new user more detailed information on installing software would be helpful. The different ways to install software, drivers, dependencies, difference in file structure to other systems etc…

I’ve seen a few links to documentation pages which default back to the Clear Linux homepage. Also not documentation but a Discord would be helpful, as a lot of distros have community discords where users can share information and help each other.

52

Documentation pages that point at 01.org are redirected to clearlinux.org now, and unfortunately if the link doesn’t work, you end up at the homepage. Please enter an issue in github when you see those.

There have been a couple attempts at Clear Linux Discords, but they really haven’t gained any traction. There is more community on the forums.

53

I think needing to report broken links in the documentation to the github is an issue of itself. If people are needing to report problems in the github when they are just looking for basic info in the documentation that’s a huge issue for barrier to entry.

I saw this article while browsing the forums and I think the criticism of installing packages still holds up: Linux distro review: Intel’s own Clear Linux OS | Ars Technica

Clear Linux is very powerful and forward thinking OS but a more detailed and user friendly documentation on installing software and workarounds when native packages aren’t available would do a lot for increasing the user base and general usability.

Edit: just as an example I’ve seen multiple posts on people being able to install .deb and .rpm files on Clear Linux but I don’t see clear information about this in the documentation. Have seen others saying Clear Linux is similar to CentOS and there should be compatibility there but as a new user I have no idea how to do this.

Easy to follow documentation on these things for new users would be very helpful.

54

just as an example I’ve seen multiple posts on people being able to install .deb and .rpm files on Clear Linux but I don’t see clear information about this in the documentation.

I believe this a case of “it can technically be done, but isn’t supported”, which would explain why it’s not documented. People shouldn’t be installing debs or rpms, they should be making requests for new bundles, I think is the idea.

2 Likes
55

I see. So if I am finding packages I’m unable to install I should ask for bundle requests from the devs?

That’s all good but wouldn’t it be best to have more info on a DIY approach in case the devs for some reason turn down our requests or don’t see it as a priority?

56

Yes, exactly as @Gorian states, whilst it may be technically possible, it’s not supported, documented or tested. We use swupd to install packages.
Please do make requests for software that you think should be included, but as you allude to, it needs to have a compatible open source license and be maintainable to include in our build system. For software that doesn’t fit in that category, there is also a 3rd party repo - Clear Fraction, the third-party repository for Clear Linux - News and Announcements / 3rd party SW - Clear Linux OS Forum

Chris

1 Like
57

oh, and Clear Linux was designed from the ground up. It’s not based on CentOS. Any similarity is coincidental, although it’s all Linux at the end of the day…

2 Likes
58

Thanks for the help. I’ll make some requests in the wishlist section if that’s the right place to ask and look into Clear Fraction.

59

Hi,

According to me, you should first structure or organized the documentation in a proper manner to cater to different user levels (beginners, intermediate, advanced). Create clear sections for each category, ensuring users can easily find relevant information.

Thanks
John

60

Fedora for example uses Weblate to translate full repository software to send the modification to upstream projects including its docs site. For docs site uses Ancora handled by a custom Gitlab pipeline.