Hacker News new | ask | show | jobs
by shevy-java 92 days ago
> had trained me to hunt for documentation in fragments: often incomplete, often outdated, sometimes already stale after barely a year.

This is indeed a problem now that google search is next to useless. And AI further degrading the quality.

I work around it to some extent by keeping my local knowledge base up to date, as much as that is possible; and using a ton of scripts that help me do things. That works. I am also efficient. But some projects are simply underdocumented. A random example is, in the ruby ecosystem, rack. Have a look here:

https://github.com/rack/rack

Now find the documentation ... try it.

You may find it:

https://rack.github.io/rack/

Linked from the github page.

Well, have a look at it.

Remain patient.

Now as you have looked at it ... tell me if someone is troll-roflcopter-joking you.

https://rack.github.io/rack/main/index.html

Yes, you can jump to the individual documentation of the classes, but does that really explain anything? It next to tells you nothing at all about anything about rack.

If you are new to ruby, would you waste any time with such a project? Yes, rack is useful; yes, many people don't use it directly but may use sinatra, rails and so forth, I get it. But this is not the point. The point is whether the documentation is good or bad. And that is not the only example. See ruby-webassembly. Ruby-opal. Numerous more projects (I won't even mention the abandoned gems, but this is of course a problem every language faces, some code will become outdated as maintainers disappear.)

So this is really nothing unique to Linux. I bet on BSD you will also find ... a lack of documentation. Probably even more as so few blog about BSD. OpenBSD claims it has great documentation. Well, if I look at what they have, and look at Arch or Gentoo wiki, then sorry but the BSDs don't understand the problem domain.

It really is a general problem. Documentation is simply too crap in general, with a few exceptions.

> if the team behind this OS puts this much care into its documentation, imagine how solid the system itself must be.

Meh. FreeBSD documentation can barely called the stand-out role model here either. Not sure what the BSD folks think about that.

> I realized almost immediately that GNU/Linux and FreeBSD were so similar they were completely different.

Not really.

There are some differences but I found they are very similar in their respective niche.

Unfortunately my finding convinced me that Linux is the better choice for my use cases. This ranges from e. g. LFS/BLFS to 500 out of top 500 supercomputers running Linux. Sure, I am not in that use case of having a supercomputer, but the point is about quality. Linux is like chaotic quality. Messy. But it works. New Jersey model versus [insert any high quality here]. https://www.jwz.org/doc/worse-is-better.html

> Not only that: Linux would overheat and produce unpredictable results - errors, sudden shutdowns, fans screaming even after compilation finished.

Well, hardware plays a big factor, I get it. I have issues with some nvidia cards, but other cards worked fine on the same computer. But this apocalypse scenario he writes about ... that's rubbish nonsense. Linux works. For the most part - depending on the hardware. But mostly it really works.

> I could read my email in mutt while compiling, something that was practically impossible on Linux

Ok sorry, I stopped reading there. My current computer was fairly cheap; I deliberately put in 64GB RAM (before the insane AI-driven cost increases) and that computer works super-fast. I compile almost everything from source. I have no real issue with anything being too slow; admittedly a few things take quite a bit of compile-power, e. g. LLVM, or qt - compiling that from source takes a while, yes, even on a fast computer. But nah, the attempt to claim how FreeBSD is so much faster than Linux is, that's simply not factual. It is rubbish nonsense. Note that OpenBSD and NetBSD folks never write such strangeness. What's wrong with the FreeBSD guys?

3 comments

Just one small note: those experiences are from 2002 and I was writing about my first experience when running it on my Sony Vaio. Running on a modern 64Gb Ram hardware is a totally different experience, 24 years later
>> I could read my email in mutt while compiling, something that was practically impossible on Linux

> Ok sorry, I stopped reading there.

Why? That's a treasured feature. https://xkcd.com/303/

AKSHUALLY...