Arch Linux Handbook

gazj · 2009-02-23 18:28:51

I am thinking of creating an Arch Linux Handbook much like Gentoo's and Freebsd's excellent ones that go into great detail. I know there is already a great installation guide, so a couple of questions.

Am I just reinventing the wheel, or do you think people will find it useful.

Does anybody know if there is some sort of handbook / documentation software out there, does gentoo use one? if so does anybody know if the source is available etc? (I guess I should probably ask gentoo forums for this, in a hope they will share there great handbook system)

Thanks Guys

Xyne · 2009-02-23 18:38:17

What would a handbook provide that the wiki doesn't?

I don't intend to discourage you if you really think this is a good idea, but my immediate reaction is that your efforts would be better spent on the wiki. Anything that's trivial/generic would be non-Arch-specific and anything that's Arch-specific will require updating at regular intervals, so the wiki format seems to be a better choice. Perhaps you could work on bringing a greater degree of uniformity and structure to the wiki instead and thereafter work on a way to take snapshots of it to create a rolling-release handbook.

Admittedly I haven't seen the Gentoo or Freebsd handbooks, so I'm aware that I could be missing the point completely.

Mandor · 2009-02-23 18:47:45

One thing that I can think of is that wiki is not really comfortable for use when offline - and many of the times you actually need the wiki, you are offline, especially if you are newer user. Some time ago I used to boot a SLAX to read the wiki - doh!

gazj · 2009-02-23 18:56:20

Sorry I should have gave a link

Gentoo Handbook http://www.gentoo.org/doc/en/handbook/handbook-x86.xml
FreeBSD Handbook http://www.freebsd.org/doc/en_US.ISO885 … /handbook/

Note the great detail they go into.

Obvioulsly the Arch Install has no where near as many steps, but the Gentoo documentation goes to great lengths to tell the user why?
Also the clarity of the Gentoo forums is second to none.

Although I do see a very valid point for putting the effort into the wiki, and the more I look at the wiki, the more I think I would be just duplicating it.

Please don't think I am just bashing our own wiki, this is not the case, the wiki is great as a wiki. I just think really percise and good explanations will help someone with no Linux expierence at all have much more chance of a succesful install if they understand the nuts and bolts of the system

Last edited by gazj (2009-02-23 19:11:39)

rson451 · 2009-02-23 19:02:04

I think this is a great idea and could possibly lead to slimming down the beginners guide if executed properly. IMHO the beginners guide is becoming much too monolithic for it's original intention.

yingwuzhao · 2009-02-23 19:36:46

Hi, gazj,

this is absolutely an excellent idea! I am sure it will further extend Arch's territory among linux users.
I think the handbook should be a comprehensive summation of the Wiki, which has many out-of-date informations, and has somewhat duplicated but conflicted info on same issues sometimes.

Compiling all the Wiki into a nice handbook will absolutely be a more than welcome work! Probably at the same time, Wiki will also be improved. I am guessing there will be a lot of work to do, and it may take a while to finish. But once it finishs, I would think that make Arch goes a large step forward!

Thanks, and I am looking forward to see your handbook.

Last edited by yingwuzhao (2009-02-23 19:37:18)

toad · 2009-02-23 20:48:44

I am an Arch newbie and find that often the wiki does assume things which I _may_ know or not as the case may be. Most of the basic stuff makes perfect sense while other is unusable.

There was a bloke who compiled all the info and sells it via the internet. Check the forum, he announced it.

I for one would be interested in the organisation/contributing.

Dieter@be · 2009-02-23 21:20:43

gazj wrote:

Am I just reinventing the wheel, or do you think people will find it useful.

Depends on what exactly your plan is.
If you intend to write a document from scratch: yes you will be reinventing the wheel and probably give up before you come even close to reaching your goal.
On the other hand, you could consider just contributing to existing pages. look at http://wiki.archlinux.org/index.php/Main_Page, this is the index of your handbook: it already exists.

dolby · 2009-02-23 21:33:19

The beginners guide is what comes closer to being a handbook. Maybe its not ideal, but its a start.

Last edited by dolby (2009-02-23 21:33:41)

Dusty · 2009-02-23 21:37:18

More or less off-topic, but there is also a print version of the Beginner's guide available:

http://shop.archux.com/content/arch-lin … ners-guide

For those complaining that the wiki isn't good enough, I suggest improving it or at least marking areas where you think it needs improving.

To the OP: If you can write a handbook that is better than the wiki, I say go for it. :-)

Dusty

ogronom · 2009-02-23 21:50:16

Worthless work. Printable versions of wiki pages are enough. If you think that wiki is not complete, fill it.
There is only one case when it would be usefull to create handbook -- it would be "official" and "trusted" (by this I mean it is created only by developers). But as I feel, the Arch community don't need this

Alxe · 2009-02-23 21:56:58

I think is a good idea, it has a con against the wiki: I can't be always improved. That's the thing with internet. I think, you could compile most of the useful things for a normal user in the handbook like how to install, and things like that. Maybe some FAQs too. It should be light and contain more "light" info than the wiki has, but considering all work spaces. Also Recommendations of applications for people that don't know lots of them and are used to Window's. (I'm one of the last... Sadly)

pogeymanz · 2009-02-24 04:02:45

I vote yes. Not too much to elaborate on- I would like to understand some of the real nitty-gritty. Kind of like a Beginner's Guide++

jacko · 2009-02-24 05:16:55

It all depends on the scope of the handbook. But to write a copy and paste guide to ' the arch way' in a handbook format is just dumb. wiki is far more intuitive for that purpose.

Though I would love to see an in depth 'handbook' on using arch 'the arch way'. IE. advanced topics on pacman/makepkg/abs. Arch's bsd style initscripts. These all have wiki pages, but it would be so much better if it was constructed into chapters in a handbook instead of random pages on a wiki.

I also think an in depth handbook on 'ARCH' related troubleshooting. Common errors, ways to fix these errors, how to effectively report these errors to the bug tracker. Things like mismatched lib's turn up all the time, would be so much easier if the community at large knew how to report these very common errors so they can be fixed faster.

That's my take on it. Also things like pacman/abs/makepkg rarely change making the maintenance of the handbook very easy. It also would clearly define what arch is and is not.

Last edited by jacko (2009-02-24 05:21:39)

Aprz · 2009-02-24 09:00:40

Well, I used to browse the Gentoo forums a lot (still do here and there) and I remember a couple of folks mentioning that the reason they prefer a handbook over the wikis, which I think they never made their wikis official and it was down for awhile (if not still down), is because so much new users try to contribute to the community and failed at it. I don't mean they'll be completely wrong, but they'll add stuff that is bias (by favoring one method over the other, forgeting to mention the other methods, or weighing pros and cons in a weird way, and Gentoo stresses choice) and things that are very nooby/cheated way to do some stuff, "work arounds" for fixing or doing things.

Honestly, I love reading a lot of Gentoo's documentation along with all the HOWTO on the Linux Documentation Project, and I prefer them over the wikis, but like using Wikipedia (for school or when you're bored), our wikis are a great way to get information quick when we aren't planning to become an expert at something or trying to be ultra formal (can't consider wikipedia a credible source in a formal essay, hehe).

Personally, I don't think you should make one. No need to make a Arch branded handbook.

zenlord · 2009-02-24 13:22:04

I think the wiki is a very good source of information, but lacks a good structure that is present in (most) handbooks. I think creating a script that takes a snapshot of specific pages/sections of the wiki whenever a user feels like it (kinda 'on the fly building the handbook'), could be a terrific idea. If this would be to hard on server performance, it might be generated weekly.

I'm always surprised there is so much information available in the Arch wiki, but it has never gotten me started me on something. I always went there to get info on a subject I wanted to find out more about. You cannot read a whole chapter in the wiki to expand your view on a something.

Just my 0.02€/$

Zl.

gazj · 2009-02-26 18:41:15

Well I am half way through writing the intsallation process. I will put it up for viewing when I have finished that Chapter. The communitys views will decide it's fate

Thanks for comments so far guys / gals

Dieter@be · 2009-02-26 18:46:23

gazj wrote:

Well I am half way through writing the intsallation process. I will put it up for viewing when I have finished that Chapter. The communitys views will decide it's fate

Note that we are changing to aif and several things will change (different way to do filesystems, different way to set keymap etc)

scj · 2009-02-26 19:16:10

The best way would probably be to create a wiki markup -> latex transformer so you can distribute nice looking pdf snapshots.

Llama · 2009-02-27 10:11:34

rson451 wrote:

I think this is a great idea and could possibly lead to slimming down the beginners guide.

Does the beginner's guide need any slimming down ? Instead of being comprehensive (aka intimidating) Arch Wiki articles always get straight to the point. This style is a jewel in its own right, IMHO.

will1911a1 · 2009-02-27 13:43:51

I always thought the wiki served it's purpose just fine, but I'll be interested in reading this when you're done with it.

Janusz11 · 2009-03-12 08:44:05

Personally I'd welcome a book about Arch Linux. Call me old school, but I prefer books on paper over computer any time. I also have a nice little book about Gentoo and its a very informative read.

But that's the flip side of the coin: first of all I think such a handbook has to be done by or at least in cooperation with one of the guys from Arch Linux who has all the knowledge about the ins and outs of this system to share some information. And then there is the fact, that the system is constantly changing. So some things that might be mentioned in a book might soon be obsolete.

That said, such a book has to contain more than just a walkthrough to the installation process and some post installation tips. For that, the Wiki will always be the better place (and I can print out the relevant information just fine for me to always have them available when I need them).

thomasknowles · 2009-03-12 10:38:21

The problem with a handbook is due to ArchLinux's nature, it would be outdated instantaneously. Greater effort could be made maintaining the wiki to a higher standard.

Arch Linux

#1 2009-02-23 18:28:51

Arch Linux Handbook

#2 2009-02-23 18:38:17

Re: Arch Linux Handbook

#3 2009-02-23 18:47:45

Re: Arch Linux Handbook

#4 2009-02-23 18:56:20

Re: Arch Linux Handbook

#5 2009-02-23 19:02:04

Re: Arch Linux Handbook

#6 2009-02-23 19:36:46

Re: Arch Linux Handbook

#7 2009-02-23 20:48:44

Re: Arch Linux Handbook

#8 2009-02-23 21:20:43

Re: Arch Linux Handbook

#9 2009-02-23 21:33:19

Re: Arch Linux Handbook

#10 2009-02-23 21:37:18

Re: Arch Linux Handbook

#11 2009-02-23 21:50:16

Re: Arch Linux Handbook

#12 2009-02-23 21:56:58

Re: Arch Linux Handbook

#13 2009-02-24 04:02:45

Re: Arch Linux Handbook

#14 2009-02-24 05:16:55

Re: Arch Linux Handbook

#15 2009-02-24 09:00:40

Re: Arch Linux Handbook

#16 2009-02-24 13:22:04

Re: Arch Linux Handbook

#17 2009-02-26 18:41:15

Re: Arch Linux Handbook

#18 2009-02-26 18:46:23

Re: Arch Linux Handbook

#19 2009-02-26 19:16:10

Re: Arch Linux Handbook

#20 2009-02-27 10:11:34

Re: Arch Linux Handbook

#21 2009-02-27 13:43:51

Re: Arch Linux Handbook

#22 2009-03-12 08:44:05

Re: Arch Linux Handbook

#23 2009-03-12 10:38:21

Re: Arch Linux Handbook

Board footer