Take the Road Most Documented | Hacker News Reader

Take the Road Most Documented

jarbus.net

134 pointsjarbus81 comments

> However, when installing Arch, I resolved each installation error with the help of the wiki

The Arch wiki is amazing even if you're not running Arch at all. In 25+ years of using Linux I've never used Arch and yet the Arch wiki is really a treasure trove. I regularly use it even though I'm running Debian (and Devuan too).

YES!

The arch wiki is amazing!

Gentoo as well.

Yep, I use Arch Wiki as a starting point even for NixOS issues, when they're not strictly Nix-specific. Before then, Gentoo wiki was the go-to, but Arch Wiki has surpassed it by this point.

I also think that the AUR is a great source of information too, since PKGBUILDs are really easy to understand and useful for determining how a program can be built and packaged, and you can go and use this to make other kinds of packages for a given program.

Yes, once you get to the competence level of being able to map over information from the arch wiki or GitHub issues your experience becomes a lot smoother.

Yes! Gentoo was my first Linux distro, and I am grateful for the wiki. It made my hard ride with Linux — it’s been 15 years now — highly enjoyable

Same. I'm hoping the push the Nix documentation team is pushing right now sets the path to something like the Arch wiki for NixOS.

So, basically like the Guix docs then

The Guix actually docs look like the current Nix docs, which I presume is not a coincidence given the nature of Guix. These are not bad docs by any means, but the Arch wiki is a wealth of documentation that goes far beyond the norms, documenting all sorts of things that are not part of the base system, including quirks with specific hardware and software. There's nothing wrong with the docs Nix and Guix have today, they're just not really the same thing as Arch Wiki. NixOS has an unofficial wiki, which is a bit more apples-to-apples, but it's relatively bare for now.

That having been said, I think I'd have a bit of trouble adopting the Guix system though, because I rely pretty heavily on the NixOS options search, and it seems Guix at this moment only has a package search.

You can also search system services / facilities:

    guix system search ...

You mean the Debian wiki is bad or useless ?

I think Arch and Gentoo are generally considered closer to upstream. So, it is less likely that you are getting os-specific advice on their wikis.

Worth noting that part of the reason the Arch wiki is more effective than the Debian wiki is that the former only deals with a single version of things, "current", whereas the Debian wiki has to address multiple releases. This makes it more difficult to prune old information or to have a concise narrative, among other effects.

I think it might be that the software in arch and the "wordware" of the arch wiki are both in sync with reality/rolling release

Arch’s docs make me simultaneously happy and sad: happy because they’re AMAZING even for the most obscure things I’ve run into… sad because they’ve given me a taste of what docs could be but aren’t.

In many cases that should be taken as a plea that you get involved and write those documentations. Writing documentation is hard, but someone needs to do it.

I think it is because it documents the individual contributions to linux, which all coexist in the Arch distribution.

Since arch doesn't generally make choices for you, the wiki IS sort of the choose-your-own-adventure installer.

Other distributions have made the choices, but they are documented in the wiki.

I assume the article is refering to open technologies since it cites the arch wiki as a reference, but if not I'd say rather than take the road most documented, to take the road most open (I would also bet they are the most likely to be well documented too).

It's of no use to have a very well documented product that you can't control which version you use (SaaS and subscription based services) and that have documentation and APIs that keep changing without warning.

Betting on open tech is also more likely to be more stable in the long run because everyone involved in it, Devs and users alike, is interested in the product first and foremost. For profit companies with closed tech are only interested in the user when doing so yields the greatest results to their investors. Once the company has to choose between invertors and your workflow, you are always going to end up losing.

Yep, I only use open source tech and forgot that people sometimes have closed source dependencies haha. Although I use Nvidia GPUs and in general the support for their drivers are still way better than AMD’s which are more open. But aside from that, the article assumes that you are using open source tech.

This is the way!

> Although I use Nvidia GPUs and in general the support for their drivers are still way better than AMD’s which are more open.

On open source desktops, my general experience with AMD GPUs has been very positive, with the main caveat being that I don't buy AMD GPUs near product launch (which, right now, is probably not a bad decision for just about anyone, since the new products are rarely a particularly good deal). I used NVIDIA GPUs on Linux from like 2004-2016 or so, and things have just changed a lot in the intervening years in my point of view. There used to be all kinds of issues, but it has started to go the other direction, and now it's getting harder to get NVIDIA drivers working right sometimes.

When people ask me personally, I recommend AMD GPUs on Linux to basically anyone that isn't actively interested in using CUDA.

Unfortunately my main use case is CUDA, haha. I’ve got hope that long term ROCm can catch up.

Oh yeah, same here. I'm not holding my breath, but I'll tell you what I'd really like: I'd really like to see Vulkan become the lingua franca of GPGPU compute. It's probably more possible for something like that to happen now than ever, since I think the majority of GPGPU usage is ML via PyTorch. That said, it's pretty obviously very different from CUDA, it feels unclear if this is really a promising path to go down.

That would be epic, never even considered this possibility

In many ways, source code is the ultimate documentation

Aka, one of the main reasons to choose 'boring' technology. Something new and experimental may have some interesting properties that make it fun to play around with, but chances are you'll have to fix everything yourself if anything goes wrong.

Meanwhile, picking whatever everyone else is using at least means resources will exist out there and that other people will have had the same issue at some point in time. Hence why I'd pick React or Vue over a newer framework, or plain HTML/CSS/JavaScript over a framework in general.

Boring technology is honestly the best technology, I’ve never regretted using boring stuff because it can usually do 95% of what I want without too much hassle. I get tempted by shiny stuff, but I’d never rely on anything new for something important

I too like boring tech and try and avoid shiny stuff. I'd like to refine this idea though: is it that I like boring tech because it's old and battle-tested, or just because it's old and I'm familiar with it?

E.g. Bazel. Is it shiny new or is it boring old? It only made v1.0 four years ago, but it's based on Blaze, which has been developed internally at the Google mothership since 2006. To a Googler, Blaze probably seems boring - does Bazel, too?

I call it "Stackoverflowability".

If you go by that name alone, and select stuff best represented on Stack Overflow, you'll get the side effect of ignoring all the best documented projects.

I guess the best term would probably be 'searchability' then. You want something where info comes up if you type it into Google/Bing/Kagi/your search engine of choice, and where there's enough of a community that other people will have experienced similar issues to you in the past.

(for this reason, it's also probably better to choose projects with unique/well known names that don't conduct their support operations on Slack or Discord).

I don't think many would call Arch "boring technology". It's a cutting-edge distro, and it is designed with the expectation that you will read the wiki, since you don't have any chance to properly install it if you don't.

I don't think it's near as "exciting" as many make it sound though. These days I usually run Debian on my personal machines, before anybody thinks it's fanboy-ism or Stockholm Syndrome.

I've been using Arch on and off for a while. Back before systemd, and it had an installer.

I can't remember anything earth shattering in quite some time. Certainly no big paradigm shifts.

Packages are up to date, but they're the developer's latest release. If something is broken, wait for the fix to be released and that's about it.

I ran ~15-20 developer workstations on Arch for a couple of years. They were there before me. Being a Java shop, we managed our JDKs/IDE outside of the system packages.

Arch stays pretty close to upstream and rolling release means you only get little updates, no version upgrades.

It is boring in the “don’t do anything unexpected and avoid catastrophic changes” sense.

Arch is not what I would call cutting-edge, and I would call it boring.

The overriding philosophy of Arch is simplicity. That simplicity pushes the burden of having some basic understanding onto the user, as many kinds of guided tutorials and wizards are anything but simple.

> it is designed with the expectation that you will read the wiki

It is designed with the expectation that you will read the documentation, which is true for many things, as a simple example, many home appliances.

boring technology for work and whatever you want to explore outside

In all my jobs, I've generally found that I'm the only 1 who ever puts effort into documentation.

Many coworkers have straight up admitted they don't document for job security.

Though in personal experience, my documentation is what eliminates my job security.

> Though in personal experience, my documentation is what eliminates my job security.

Is that what you meant to write? It sounds like you agree with your coworkers.

I always tell people if you can't be fired, then you also can't be promoted to something else more interesting. If someone can take over for you that means you can go do something else.

How often do people actually get promoted to something "more interesting" though?

People move to other projects all the time.

Those aren't promotions, they're lateral transfers.

>I always tell people if you can't be fired, then you also can't be promoted to something else more interesting. If someone can take over for you that means you can go do something else.

In my experience, if you want a raise or promotion, you need a new job.

You must always be cognizant of the carrot being held out in front that you will never get.

In a good large company they open up jobs in other departments to current employees first. However if you apply your manager is consulted on if you are allowed to move. There are also promotions to management or architecture - both of which you may or may not want (and remember you may change your mind on this in a few years!)

As if meaningful promotions happen to more than 0.0001% of all programmers everywhere.

Ironically sticking with a Windows on the Dell XPS would have proved even more reliable and stable than Arch.

And it would have been more documented.

For distros the best one is the most thoroughly tested and debugged. That definitely used to be Ubuntu back in its glory days. I'm not sure who it is any more - perhaps fedora.

Agreed, I was using Arch until I got tired of fixing broken stuff. I then thought I'd rather have a distro where things weren't broken in the first place, Ubuntu worked well for me in that regard

I use Manjaro for years with zero issues, though for context I have to say that I make it a goal to always update it at least once a week because rolling release distros can be fickle if you upgrade them rarely.

And never once had a problem.

I switched from Ubuntu to straight Debian... but I have been testing Opensuse and had good experiences with it so far. I am super excited for theor upcoming Slowroll edition.

I would guess it depends on the environment you operate in, but it feels to me (emphasis on feels) that the top two are RHEL and Debian. Both are very stable, tested, and have tons of community support.

1. RHEL: Despite recent business/licensing shenanigans they still sponsor an enormous amount of work that benefits the whole open source community. Very big in enterprises, web hosting, and most cloud providers. Has multiple "cousin" distros like Fedora, CentOS Stream, Rocky, and Alma if you have no need or want to be a direct Red Hat customer.

2. Debian: Has a pretty old-school development process, which results in a very stable general purpose Linux-based OS with a (somewhat) predictable release cycle and very few frills or non-essential baggage. More popular among those who shy away from distros with commercial attachment because the Debian community leans toward Free Software (in the GNU sense). Quite popular in embedded and small systems (e.g. Raspberry Pi), cloud images, and containers. The upstream for a number of other quite popular distros.

IME it's Fedora because it's still RHEL's upstream so they dedicate engineering time to actually fix stuff

Not sure. Often I'd rather have a distro that breaks a little more often, but is easier to understand and fix when it breaks, than one that's a little more tested but changes more often and is less well documented. If I wanted a polished product, and didn't care about fixing it myself, I wouldn't be using Linux in the first place.

> If I wanted a polished product, and didn't care about fixing it myself, I wouldn't be using Linux in the first place.

Then what would you be using? Windows certainly isn't a "polished product", and from all the problems I've read with people using Macs, MacOS doesn't seem to be either.

It has been a lot of distributions for a long time - e.g. openSUSE.

I am not an Linux expert by any stretch but I also used quite a few distributions (though very few in anger i.e. actively for long periods of time).

To me Arch and its derivatives (e.g. Manjaro and EndeavourOS) and Void Linux are the best nowadays.

But isn’t Ubuntu thoroughly beaten around the bush?

If there’s a Linux problem, most likely someone solved it on Ubuntu - or you have a different experience?

Usually, yes, and I do appreciate that about Ubuntu, but a lot of the answers/guides/blog posts I find are meant for 14.04-18.04 and are often not relevant any more. It's hard to tell sometimes if that's Ubuntu changing things, or GNOME, or Wayland, or other things under the hood.

I have fallen back to Debian for after using Ubuntu for almost as long as it existed.

I can't tell exactly what pushed me over the edge, but the release cadence which I love so much about Ubuntu (easy to plan for) just wasn't enough to keep my there anymore.

I installed Debian on a home server instead of Ubuntu, and it just feels much snappier. After all the "everything's a snap!" and "here are all the packages you COULD have upgraded if you'd paid for Ubuntu Pro!" bullshit, I think I'm going to go to Debian unstable for my desktop as well.

Make sure you know what you're doing here: generally what people use is Debian testing, not Debian unstable, which is actually pretty unstable.

Unstable only gets packages a week or so before testing.

Oh hm, thank you. Is testing rolling release as well? I would like something more stable than one-week-old packages, true.

> I can't tell exactly what pushed me over the edge

It was definitely snap for me.

Agreed, I've been bouncing back and forth between Debian and Ubuntu since Debian 7 came out, and I feel like I've been gradually caring about Ubuntu less and less since 12.04. The snap thing has been just kind of irritating, especially Firefox being snap by default (even, to my surprise, if installed via apt!) which breaks the Gnome integration and has (had?) worse performance than the .deb version.

I did just read that Mozilla is releasing an official .deb package of Firefox for those of us who would rather not use the snap version, and I plan to give it a shot. But I'm thinking about transitioning back to Debian on some of my machines instead of upgrading them to 24.04.

Have spent a lot of time trying to integrate Ubuntu into a Red Hat environment. It's close but there's enough differences to give you an ulcer.

Ubuntu does things its own way, and that's only become more prevalent over time. Ubuntu answers aren't always relevant to other distros

Nowadays it's "take the road most LLMed", a sentiment I've read time and time again as some chose not to work with newer libraries because they are not in the ChatGPT training set.

I mention this in the article, and there’s definitely some truth to it. It reminds me of how we might trap ourselves in earth with all the space junk we generate - for libraries, we might trap ourselves to using tools that reached enough training data and will hurt the development of new tooling

Believe it or not I had actually read the article, somehow minus that single line :P.

I don't think this situation will last long though, there's going to be a way to update the models continuously, but even so, they might remain "better" at some technologies than others, what does that say about them, if anything?

We really are effing doomed

Good advice to always document your own projects if you want traction!

When writing a new library with little adoption, with a goal of driving adoption where do you think effort should be dedicated between documentation, features, and promotion?

I think they all together a bit. I see documentation as a way of marketing features that have been written... but it doesn't help until people discover the project.

How do you know when documentation is holding you back?

Probably features. If existing libraries can already do what you are marketing, and are better documented, there’s no point in using your library all else held equal. I think first you need to build distinguishing features to get people to notice the tech, and then document it to make it more usable and drive adoption into actual software

And this is why I obsessively document my software.

What did you view the wiki on during installation?

An iPad haha

This post is annoying in that it doesn't tell you what laptop the person got to have a good experience. It tells you the bad example but not the one that worked.

Good point, apologies. I got a Razer Blade 2021 15”, because I needed a GPU and it worked with Arch. The only issue that I could have had according to the wiki was a trackpad issue that had a workaround.

really like the font and great article btw.

Thanks so much! It’s GNU Unifont. I kept switching between fonts every few months until I discovered it, I’ve been using it for the past few years now with no intention of switching off :D

Reply on news.ycombinator.com