Arch Linux Documentation

redge · 2007-01-06 04:51:57

Is anyone in charge of developing Arch Linux documentation? From an interview that I came across on the net, I gather that there is. If so, could I ask what the programme is to improve documentation and what the target dates are?

If there isn't anyone in charge, are there people who would be interested in working on documentation, maybe within the Arch community, but maybe outside on an independent site?

Dusty · 2007-01-06 07:46:39

I used to be an Arch Linux documentor. The project basically died when I quit, but the wiki (wiki.archlinux.org) was one of my prime contributions. It allows everyone to be an Arch Linux documentor.

We've been pushing for more active wiki maintainers in addition to the casual work done by many users. Foxbunny was doing a great job, but recently decided to move onto some other work. These people would be semi-official documentors, I suppose, doing all their work right in the wiki so others can help.

To answer the question about someone being "in charge", I guess its me, as wiki co-admin. However, I haven't been paying too close attention to what is actually happening in the wiki, as far as the contents go. Foxbunny was organizing everything and writing meta-documentation describing how the organization would work. We're also actively looking at new wiki software that is easier to use, maintain, and navigate. If you have any questions, post here and one of the active wiki-members will be happy to answer.

Dusty

redge · 2007-01-07 03:31:08

Hi Dusty,

Thanks for your your response. Here's what seems to me (rightly or wrongly) to be the problem.

I have a spare computer that I can just play around with. In the last few weeks, I've installed several Linux systems on this computer. Most recently, I've installed Arch 7.2.2 and .8 and, yesterday, Gentoo. At this point, I've decided that I am going with one of these two systems.

It seems clear to me that the Gentoo documentation is vastly superior. I say that objectively, and recognizing that Arch is being maintained by a pretty small group of people. I guess that the question is this: is there some point in improving Arch documentation, and how might that be done? I ask that question recognizing that there are people, at least as far as I can figure out, who don't seem to be much interested in making Arch more transparent. The funny thing is, these are people who probably "respect" Gentoo and its users, but who don't know, or don't care, that Gentoo is documented much better.

I wrote my post because I was thinking about spending some time working on documentation, assuming that there was any interest. Meanwhile, in the last 24 hours, I've had a pretty good experience doing a manual install of Gentoo (in part because of how it is documented), and right now it isn't obvious to me why I wouldn't just stay with Gentoo. Yes, Gentoo takes more time, but you know, it is also a lot more transparent, precisely because of how it is documented, starting with the installation instructions.

Surely Arch users, especially those who take an elitist attitude, have got to wonder when someone says that doing a manual install and configuration of Gentoo is more transparent, more educational and, frankly, easier.

Dusty · 2007-01-07 05:01:44

I couldn't say for sure, but I think most people who use Arch use it because it makes sense to them. Once they figure it out they don't need documentation. :-D

Better documentation is something that most of us would like to see, but few of us have put much effort into. I suppose its because other things are more interesting to the typical Archer. Its certainly not because we want to make things difficult. If you search the forum, you'll find plenty of posts by people either suggesting that "someone" should improve the documentation, or even volunteering to do it, but nobody ever does.

If you or anyone else wants to work on better documenting Arch, we'd love to see it. We want it done in the wiki; most of the information is there, it just may be hard to find. If someone can put a concerted effort into organizing and consolidating this information, I'm sure no-one will complain.

Dusty

redge · 2007-01-07 05:12:11

Once they figure it out they don't need documentation.

If you search the forum, you'll find plenty of posts by people either suggesting that "someone" should improve the documentation, or even volunteering to do it, but nobody ever does.

If someone can put a concerted effort into organizing and consolidating this information, I'm sure no-one will complain.

Honestly, reading your post, I don't see why anyone who can write, and might spend time on documentation for this project, would invest time in doing it. It sounds like nobody cares, and that doing it would be thankless. Personally, I think that the lack of emphasis on documentation is a mistake, in fact quite a large mistake, but that is just my view. In any event, given what you are saying, I'm not going to spend time on it.

The timing of this discussion is funny. After spending a lot of time today working with a co-author and a graphic designer on the finalization of a book, my co-author and I have a manuscript going Monday morning to a New York literary agent. I don't think that we would have spent a lot of time writing this book had we been told that if we "put a concerted effort into" it, "no-one will complain".

There is something about disregard for documentation that is ridiculous. Nobody can run a computer without documentation. So it is just a question of where one gets it. If one thinks that the mark of an Arch user is that documentation is unnecessary, what one is really saying is that the documentation should come from books or man pages. And if Arch users who turn up their noses at documentation are serious, why not lobby to get rid of man pages and push everyone to books? For that matter, why not tell people that if you are really cool, you will figure it out without reading a book? And why have a forum?

Let me ask a basic question, are Arch users proud of the fact that, compared to Gentoo, Arch documentation is pathetic?

gradgrind · 2007-01-07 07:50:27

I don't use gentoo (though I did have a couple of brief flings), but I do admire their attention to the documentation. In this respect it is something of a bright light in the often rather dark linux landscape.

Documentation is unfortunately time consuming, especially when the target is constantly moving, as is pretty well unavoidable in the often uncomfortably dynamic world of computer software. Who in this day and age has the time and inclination? It seems people who actually enjoy writing documentation are a bit of a rarity.

So, redge, if it's that important to you, I fear you may be right - go for gentoo. For me, at the moment, the relative structural simplicity of Arch is more important. I, too, find the documentation (and the attitude) in some respects inadequate, but that's life. Nobody's perfect, and certainly no linux distribution is.

Lone_Wolf · 2007-01-07 13:55:05

From what i have seen of Gentoo doucmentation (mostly about ebuilds) it is indeed of good quality.

Personally i am someone who likes to find out things for himself.
The wiki/ forum are often my starting point. While they don't always give the correct answer, they are very valuable for getting me on the right track to get the answer.

(Yes, i do feel this forum is also a documentation source).

To put it short :
If you want most of the answers to be in 1 place, gentoo doc is far better.
To me that's not a prime concern.

Having said that , it would be nice if the wiki was more uptodate.
It appears that wiki pages are started when a user finds something of interest, but often forgets to update it when things change.
(i'm guilty of that too).

arooaroo · 2007-01-07 14:25:07

Is the issue not being exaggerated slightly? One could be forgiven for thinking that Arch's documentation consists of a 10 line INSTALL file!

When I installed Arch I followed the Arch Install Guide which was - and still is - accessible from the AL homepage and I didn't really run in a single glitch.

Sure, the install guide is not as large as Gentoo - I'm not sure if that's a blessing or a curse. Generally there's no such thing as too much documentation, but I think we shouldn't necessarily judge Arch for having less as it's somewhat simpler to install and maintain.

What I like about Gentoo is that they go to great lengths to get decent sized groups of contributors around given areas in the project. So they have a dedicated team of documentors, which is great as it means even if one or two become bogged down with external commitments, the overall task-in-hand doesn't grind to a halt.

So yeah, more docs (and the wiki needs some cosmetic improvements) but I can't accept that the current state of documentation is so dire as some imply.

ozar · 2007-01-07 16:12:32

I've been using Arch for a couple of years now (having come to it from Gentoo), and I've never felt that there was a lack of good documentation for Arch.

Just my own experience with it...

Dusty · 2007-01-07 17:53:15

redge wrote:

Honestly, reading your post, I don't see why anyone who can write, and might spend time on documentation for this project, would invest time in doing it. It sounds like nobody cares, and that doing it would be thankless.

For the most part that's true. I don't think anybody aside from Judd ever really gave me much of a thank-you for the work I did. However, I also don't consider that the time spent was wasted.

Let me ask a basic question, are Arch users proud of the fact that, compared to Gentoo, Arch documentation is pathetic?

Not proud, just indifferent. I don't think Gentoo users are terribly concerned by the fact that their package manager is, in comparison to pacman, pathetic either.

We work hard here, we volunteer our time, and we do the best we can. If you prefer Gentoo for any reason, we really won't try to force you to believe in Arch instead. Things aren't perfect here, but we generally don't have much use for people who criticize the way things are done without pulling up their sleeves and helping out with the solution.

Dusty

lucke · 2007-01-07 18:14:17

Dusty, thank you for your commitment in improving the documentation!

I think that having an exquisite documentation isn't (or shouldn't be) an aim per se. It's all about how documentation is used. You have an install guide which should be enough even for an inexperienced user to get base system up and running (which obviously isn't as big as gentoo's, because Arch doesn't take two weeks and a multitude of commands to install ;-)) and then you have some more or less Arch-specific instructions how to set up some things in Wiki. All the more general stuff is available through google (also including gentoo's wiki).

If there's anything you wish to have documented, ask and we'll try to fill the blank. It's hard for people to write some random stuff, wondering what others would like to have documented.

I never personally had any problems with Arch's documentation and, mind you, I wasn't born (nor still am) a Linux guru.

Zoranthus · 2007-01-07 18:16:17

I don't think every Linux distribution needs to provide all available info on all topics dealing with GNU/Linux. There is good info available on the topics that are Arch-specific already. If I want to know something about the vi syntax, I google or see the man pages.

And thank you, Dusty.

majikstreet · 2007-01-07 18:23:43

Yes, Thank you Dusty!

In my few months with arch on a spare pc, I haven't seen a lack of documentation.. The install guide is perfect.
The gentoo install guide is a freaking BOOK... Arch doesn't need that.

Also, because arch is less recommended for extreme newbies to linux, that's part of the reason less docs are needed. Ubuntu for instance has a lot of docs (but less organized IMO), but that's because more newbies use it..

Arch users tend to be able to figure things out.. And arch has excellent forums and the wiki..

majikstreet

gradgrind · 2007-01-07 19:37:03

Indeed, thank you Dusty and everyone else who has contributed to the Arch documentation, some of which I have found really helpful.

If there's anything you wish to have documented, ask and we'll try to fill the blank. It's hard for people to write some random stuff, wondering what others would like to have documented.

Good point.

But it is also worth bearing in mind that there are quite a number of people who can't or won't read the documentation regardless of how good it is. For all I know there may be good reasons for this, too - I withhold judgment. What impresses me repeatedly is the apparently endless patience and friendliness of many forum and mailing list contributors who are always glad to lend a hand if they can. This form of documentation should definitely be taken into account, and I think here Arch ranks quite high.

cactus · 2007-01-07 21:15:19

Dusty wrote:

We work hard here, we volunteer our time, and we do the best we can. If you prefer Gentoo for any reason, we really won't try to force you to believe in Arch instead. Things aren't perfect here, but we generally don't have much use for people who criticize the way things are done without pulling up their sleeves and helping out with the solution.

Very well said Dusty. I feel that paragraph captures the mindset of many in this community.
8)

picpak · 2007-01-07 21:24:57

If there's one thing that should be added to the install guide, it's that video drivers should be installed manually with the prefix "xf86-video-drivername". That one stumped me a little.

redge · 2007-01-08 02:15:32

Dusty wrote:

Things aren't perfect here, but we generally don't have much use for people who criticize the way things are done without pulling up their sleeves and helping out with the solution.

As should be obvious, the whole point of starting this thread was to get a sense of whether it is worth my time to work on documentation. If I've come to the conclusion that it isn't, it is because users don't seem to think that better documentation is necessary. Which is fine.

Believe me, I have enough to do on a book that my agent is excited about without dedicating time to writing documentation for a project whose users think that they don't need it, and whose former head of documentation sounds distinctly ambivalent about whether anyone gives a damn.

I get the sense that there are a lot of people involved in this distribution who like to pretend that deficiencies are strengths. I also think that the distribution is undermanned. Normally, if a project is undermanned, the idea is to bring people on-board. Trashing people who explore the possibility of getting on-board, and who in the process ask some hard questions, given that getting on-board involves a commitment of time and effort, is not necessarily a clever strategy. Nor am I impressed, having made a pretty obvious statement about Arch v. Gentoo documentation, by an attempt to sidestep the issue by referring to the relative merits of package managers, a discussion that has nothing to do with what this thread is about.

Anyway, having read what people have to say, the question in my case is now academic. There is no way that I am going to dedicate 8-10 hours a week to this project if people think that spare, and rather disorganised, documentation is a badge of honour. Besides, it is so much easier to write the occasional post.

nogoma · 2007-01-08 03:32:23

redge wrote:

I get the sense that there are a lot of people involved in this distribution who like to pretend that deficiencies are strengths. I also think that the distribution is undermanned. Normally, if a project is undermanned, the idea is to bring people on-board. Trashing people who explore the possibility of getting on-board, and who in the process ask some hard questions, given that getting on-board involves a commitment of time and effort, is not necessarily a clever strategy.
Anyway, having read through this thread, the question in my case is now academic. There is no way that I am going to dedicate 8-10 hours a week to documentation is if people think that spare documentation is a badge of honour. Besides, it is so much easier to write the occasional post.

This is all fair enough; if you don't feel that your efforts would be useful, then by all means don't "waste" time on it (I say this from the point of view that I think you should feel fulfilled by your contributions to this kind of community, not "I didn't like what you said, so I don't want your help" kind of way ) . I think a lot of the feelings expressed in this thread are summed up by the last line of your post, but in a more positive way. That is to say, the Arch Forums are fantastic, and people are willing to answer questions that come up here. As a result, they are maybe unwilling to spend time adding stuff to the wiki that may be too general to cover specific questions anyway. I do think there are a lot of projects and common questions that can be summed up in informative wiki pages (and a lot of things *are* covered there). Perhaps naturally, the wikipages that *do* get written are ones that involve projects people are personally involved or interested in (I put in a wmii wiki page at one point when I got into ruby-wmii, but even that has fallen behind wmii releases at this point).

There have obviously been documentation efforts, and plenty of people that stop by to say "Hey, I'd like to help". However, I think the stopping point for a lot of people is either a) What needs documenting and b) Gee, I don't know anything about the stuff that needs documenting! I actually think the best wikipages are born of arch forum threads; when a discussion has a lot of great tidbits, somebody usually chimes in and says "Hey, somebody make a wikipage", or better yet, "Hey, I already made a wikipage, check it out and add stuff if you want". This works, because obviously a lot of people reading the threads that end up creating the wikipages *know* about the subject. Also, people are immediately alerted in the thread that there's a new page, and may say "Hey, I can add to that", as opposed to a system where people are just going through adding pages and hoping other people notice and add stuff too.

So, in summary, I guess I'd say that documentation is great, but due to the nature of Arch, our efforts work the best when the ball is already rolling in the forums. Which really is the best way for a "smaller" distro like Arch, IMO. Maybe to you this still seems like a "deficiency" that Arch users think is a strength; it seems to me to be more of a natural product of a really active user community (where instead of there being a group of people dictating what documentation is needed and such, those things that come up in community end up being codified in the wiki).

Personally, for me, I think a good documentation effort would be to keep your eye on long or very active threads; if they look like they have juicy info in them, condense it into a wikipage and announce it in the thread. Of course, that's just one Archer's opinion, and not necessarily of one that knows what he's talking about . I do agree that there are steps that could be taken to make tackling documentation easier (and I am aware that Dusty has the "Wiki volunteers wanted" thread for this) for people that "want to lend a hand", and I'm certainly not saying the efforts that have gone on so far have been wasted. I just like the idea of the really active community in the forums being leveraged to help the "static" documentation in the wiki. See a thread that indicates the install guide is lacking info is confusing? Make the wiki edit! See a thread with great new info? Start a new wiki page! See a thread born of BAD INFORMATION in the wiki? DEFINITELY update the wikipage! Embrace the wikiness of the documentation; worry less about "who maintains this page", and more about "what are the actual issues users are having, and can I change something right now to help?". Coming from this angle really reduces the feeling of being overwhelmed when loading up the wiki to edit it with no particular agenda in mind... rather, you have particular pages in mind, and you know they will be immediately useful.

Cripes, this was a long post. Sorry! Hopefully it will encourage people to contribute, even if it's just a small edit on a single page, without them worrying about becoming documentation maintainers. You don't have to be an expert at everything or anything, but being a part of a community is contributing what you can when you can. Oh, and yeah, this post probably looks funny coming out of the mouth of an "Occasional poster"; I'm actually on the forums daily, looking for spots where I can answer a question, and do so when I can.. my lack of posts is simply an indication of my not knowing enough .

Oh, and as to the response to Dusty's response... I feel like we see these kind of responses a lot on the forums, and I kind of wish people wouldn't take such umbrage at these comments. These comments are a result of people *knowing* the community. It doesn't mean that they think your idea is stupid, it just means that they're telling you what has been true in the past, and why certain things maybe don't work out. It doesn't mean you shouldn't feel like you can contribute how you want; it's open, go for it. Get the ball rolling; the community may embrace it gladly. If it didn't, well, you contributed out of love of the community, and that will certainly still be appreciated.

Dusty · 2007-01-08 03:46:30

I confess, I am amazed by your literary skill. I've never met anyone who had an agent before. I'd be delighted if you could provide us with a link to your work. I'm not permitted to have an agent because my submissions are anonymously peer-reviewed.

We typically frown on arch-vs-<insert> discussion here. They get out of hand. That's not to say we don't like new ideas, but its better to have specific ideas implemented (for example: http://bbs.archlinux.org/viewtopic.php?t=27972) than to have opinionated discussion with no result. Having said that, there is an Arch-vs-Gentoo discussion here: http://bbs.archlinux.org/viewtopic.php?t=24710 that you may be interested in participating in. If you come up with anything useful, you may want to add it to our (gasp) documentation on the subject here: http://wiki.archlinux.org/index.php/Arch_vs_Others

Now, you may have understood my mocking a little more accurately if you'd done a forum search and discovered you weren't the first "clever" volunteer we've had. For example, here: http://bbs.archlinux.org/viewtopic.php?t=26405 You may also be surprised to find out that I have indeed tried to get more people involved in documentation, the latest discussion being here: http://bbs.archlinux.org/viewtopic.php?t=26508

So, you see, my opinion of your abilities to document is marred by the fact that you don't know how to do a forum search. I fear your agent may find you didn't research your work too well, but that's perfectly acceptable when you know more than the collective conscious so cleverly indexed by Google.

I'm also impressed by your ability to jump to conclusions with Olympian ease. Having reviewed this thread, I notice that no-one seems to think that "rather disorganized documentation is a badge of honour". Some seem to think the documentation is fine as it is, others seem to agree that it needs work. As I said, "not proud, indifferent". I'm not too sure how you managed to extract that meaning from this thread. Researching without searching first is an impressive skill, but its nothing compared to researching without reading, I am indeed astonished.

Your real name wouldn't happen to be John Dvorak, would it?

Dusty

redge · 2007-01-08 04:01:50

Nogoma,

Not too long at all, and very interesting.

Dusty,

Actually, I have already read several of the threads to which you refer, and my comments are about my overall impression of Arch, not restricted to this thread. I assume that it is permissible to express views that go beyond the current thread? You are now in full-blown attack mode. There is no point in pursuing this discussion.

T-Dawg · 2007-01-08 04:10:39

redge wrote:

There is no point in pursuing this discussion.

Good. Then it should be ok to lock this thread so that others do not.

Dusty · 2007-01-08 14:00:24

Actually, I want to take a second to apologize for my last post, both to redge and to other newcomers that may have been put off by it. Its not a model of how we generally treat people wanting to help out. So its better not to follow this example.

I recently reprimanded a user for their treatment of a newcomer. Sometimes we have to also censor ourselves.

Dusty

Arch Linux

#1 2007-01-06 04:51:57

Arch Linux Documentation

#2 2007-01-06 07:46:39

Re: Arch Linux Documentation

#3 2007-01-07 03:31:08

Re: Arch Linux Documentation

#4 2007-01-07 05:01:44

Re: Arch Linux Documentation

#5 2007-01-07 05:12:11

Re: Arch Linux Documentation

#6 2007-01-07 07:50:27

Re: Arch Linux Documentation

#7 2007-01-07 13:55:05

Re: Arch Linux Documentation

#8 2007-01-07 14:25:07

Re: Arch Linux Documentation

#9 2007-01-07 16:12:32

Re: Arch Linux Documentation

#10 2007-01-07 17:53:15

Re: Arch Linux Documentation

#11 2007-01-07 18:14:17

Re: Arch Linux Documentation

#12 2007-01-07 18:16:17

Re: Arch Linux Documentation

#13 2007-01-07 18:23:43

Re: Arch Linux Documentation

#14 2007-01-07 19:37:03

Re: Arch Linux Documentation

#15 2007-01-07 21:15:19

Re: Arch Linux Documentation

#16 2007-01-07 21:24:57

Re: Arch Linux Documentation

#17 2007-01-08 02:15:32

Re: Arch Linux Documentation

#18 2007-01-08 03:32:23

Re: Arch Linux Documentation

#19 2007-01-08 03:46:30

Re: Arch Linux Documentation

#20 2007-01-08 04:01:50

Re: Arch Linux Documentation

#21 2007-01-08 04:10:39

Re: Arch Linux Documentation

#22 2007-01-08 14:00:24

Re: Arch Linux Documentation

Board footer