Comment by capt8bit | Hacker News Reader

Comment by capt8bit | Hacker News Reader

"I've seen good documentations, but nothing beats the Arch Wiki. It's the most comprehensive Wiki you could imagine."

I have heard this a number of times from Arch Fans, but I think I disagree. While I have referenced their wonderful Wiki often for "cook book" style answers (like how to fix URXVT+Tmux interactions), I do not view it the same as good documentation. I would also not really call it "comprehensive". To me, good documentation is as comprehensive as possible of the entire subject, and not just a "how to" on configuring it to look or behave like another user's installation.

Compare the Arch wiki to The OpenBSD FAQ [1], the FreeBSD Handbook [2], or good man pages [3]. The FAQ and Handbook have thousands of pages of comprehensive documentation and examples. A well written man page should be capable of answering most of your questions and allowing you to determine what actions you want to take.

I prefer the comprehensive documentation, or thorough man pages. Although, I definitely appreciate the usefulness of the "cook book" style Arch wiki.

[1] http://www.openbsd.org/faq/ [2] https://www.freebsd.org/doc/handbook/ [3] http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man4/...

I completely agree that we need comprehensive documentations. That's irreplaceable when you need to properly configure something. Good manuals are mostly used as a reference.

The Arch Wiki is something different. It guides you step by step how to reach your destination, and that's what most of the users need.

I'd call the Arch wiki comprehensive, but not cohesive. A prerequisite for cohesive documentation is that the system it's documenting is cohesive. The BSDs, as you noted, have cohesiveness down to a science, and their documentation reflects that.

Take as an example the network configuration for FreeBSD [1] and Arch [2]. FreeBSD, because it's a cohesive system, is able to document the One Correct Way of configuring the network.

The Arch instructions are much more "choose your own adventure", but that reflects the array of actual choices that you have in Linux for network config. Should you use systemd-networkd, dhcpcd, netctl, ifplugd, etc? Or maybe some combination? If you need wireless networking [3] which connection manager do you want to use? How is it going to interact with the thing managing your wired networking?

Linux, for better or worse, gives you a very fragmented set of options compared to more cohesive systems like the BSDs. The Arch wiki does a good job of documenting those fragmented options.

[1] https://www.freebsd.org/doc/handbook/config-network-setup.ht... [2] https://wiki.archlinux.org/index.php/Network_configuration [3] https://wiki.archlinux.org/index.php/Wireless_network_config...

The documentation ethic comes, for better or worse, with somewhat of an RTFM ethos. While I am considering Arch for my enroute ThinkPad, Ubuntu is still a consideration because of AskUbuntu on StackExchange. QandA offers an alternative set of community standards in regard to support.

The Arch Wiki is a bit of a mix. Part documentation, part how-to guide, but it's still one of the best references to understand how stuff works (and how to use it) in *nix in general.

I do agree though, that OpenBSD has by far the best documentation out there.

Reply on news.ycombinator.com