You are not logged in.

#1 2002-11-12 04:34:44

sarah31
Member
From: Middle of Canada
Registered: 2002-08-20
Posts: 2,975
Website

?

i have been looking over the hotly debated discussion of the documentation and i have been rather mystified. Personally I found it complete enough to get me online and on irc to get the remainder of my problems solved.

this is not to say that the documentation does not need improvement. I think one of the single most important things that has not been mentioned so far is the infamous filesystem upgrade and the "protection" that pacman has to prevent one's system from "getting screwed up".

by fluke when i first did a major upgrade of arch i noticed that filesystem was one of the upgrades. curious as to what this meant I checked out some of my files afterwards and sure enough rc.conf and a few other important files were "upgraded" and the previous information i had entered in them was now gone. I quickly fixed all this up. then browsing the forum i noticed that there was a means of preventing this from happening every time i upgraded.

in your pacman.conf there is a section labeled as NoUpgrade. in there you list such config files as rc.conf, rc.local, and so forth. problem solved.


AKA uknowme

I am not your friend

Offline

#2 2002-11-12 06:04:30

almostlucky
Member
From: California, USA
Registered: 2002-09-30
Posts: 16

Re: ?

sarah31 wrote:

in your pacman.conf there is a section labeled as NoUpgrade. in there you list such config files as rc.conf, rc.local, and so forth. problem solved.

I think those should be in pacman.conf by default in .4

Offline

#3 2002-11-12 09:50:54

Jeepster
Member
From: Hull, UK
Registered: 2002-08-13
Posts: 15

Re: ?

I`d rather pacman itself was fixed/patched so that any major /etc/* file was plonked inplace as .new that way your old one stays inplace and can be diffed against the new one.

Offline

#4 2002-11-12 09:54:49

Arielext
Member
From: Amersfoort, the Netherlands
Registered: 2002-08-12
Posts: 362
Website

Re: ?

Agreed, it's nice to have the new config files beside your old ones so you can see if something must change in your 'old' config files or not.
I remember my hastles with dhcp back in the 0.2 time. The new script was much more easier. But don't make the new config default. Think apache ... think httpd.conf smile


apt-get install arch

Offline

#5 2002-11-13 01:48:18

scottro
Member
From: NYC
Registered: 2002-10-11
Posts: 466
Website

Re: ?

I always hate disagreeing with sarah31 as she's so helpful to me, but I think that getting on irc to get the answer isn't the answer.  smile  (How is that for bad grammar?)

Yes, I was able to solve my problems as well (although I took the long way around with overlooking lilo last time--thanks Jeepster, you'd think an old Gentoo hand like myself would have realized about mounting /proc.  However, I suspect that Arch is going to become more popular sooner or later, and then you're going to get an influx of people who aren't experienced.

Improving documentation is a good thing--or do you fear that Arch will get dumbed down?

I don't think that will be an issue yet--it will have to become far more popular before that happens. At present, it's got a small but loyal user base, mostly experienced, mostly coders and/or admins.  We're all used to documentation that is incomplete.  (Although I think that the documentation that does exist is clearly written).

Do we want to say (I feel as if I'm overstepping bounds in a way, saying we, as I'm not a part of the Arch development team or anything, but what the heck, I'm a user) well, if you can't figure out that your DHCP isn't working because you didn't install dhcpcd, you shouldn't be using Arch?  I don't think it's been a hotly debated topic--simply that someone new to Arch had several suggestions for the documentation and has offered to do it.

Jeepster and you (sarah31, that is) solved all my problems on IRC too (though I never did get sound working on that box--however, even RH which is excellent at hardware detection couldn't get it going--finally gave up and made it a BSD box, as FreeBSD's generic sound thingie works, and Arch's sound works fine on all other boxes). Yet it would have been nice to have slightly more detailed documentation, so I wouldn't have had to go on IRC. 

BTW, to go COMPLETELY off-topic, anyone see Buffy tonight?  That was a peculiar episode.

Scott

Offline

#6 2002-11-13 03:14:37

sarah31
Member
From: Middle of Canada
Registered: 2002-08-20
Posts: 2,975
Website

Re: ?

well i just could not think of a response to this that does not put me in a bad light so i gave up. suffice it to say i really was disappointed to see so many people get so bent out of shape about the documnetation. you don't like it fix it. if you wannna debate it you know where you can find me.


AKA uknowme

I am not your friend

Offline

#7 2002-11-13 03:32:20

apeiro
Daddy
From: Victoria, BC, Canada
Registered: 2002-08-12
Posts: 771
Website

Re: ?

I agree wholeheartedly -- Arch needs more documentation.  The little we have was written by me and probably doesn't cover all the obvious points.  As most of you well know, it's not a good idea to write documentation for a project that you are coding on.  You're just too close to the code and you often can't see the perspective of the average user.

So we're unanimous:  more docs!!  With that said, we just need some volunteers to step up and get it done.  The existing arch developers are bogged down as it is, and we have more pressing things (like 0.4's release) to get done.  Gyroplast has started his own FAQ, and Scottro has contributed some tips n' tricks - both are linked to from the docs page on archlinux.org.  That's all it really takes -- start some documentation of your own, fill in all the holes that I've left.  Then submit it to some archers for constructive criticism, and the iterative development cycle will run its course.

I was planning on putting out a more formal "call for help" after 0.4, but you forum people should know about it now anyway.  After Dragon is out, I'll be looking for people to help manage the unofficial package tree (sarah31 has already volunteered to be one) and import packages from the /incoming area on the ftp.  There are about 300 packages in there right now.  And of course, the search will continue with other areas: coding, docs, bug testing, package testing/maintenance.  There's always work to be done.

So there it is.  I want Arch to be the best it can for the people that enjoy and support it.  But this is a community thing, and I can't do it alone.  A select few of you have graciously offered your time and expertise when you can spare it, and I appreciate that very much.  The first five* that come to mind are jproctor, jeepster, ody, sarah31, and elanthis.  You recognize that things need to be done and you do them, without stepping on other peoples' toes.  Kudos and thanks for the help.  smile

* not to say there aren't more of you helpers are out there, I just can't list em all.  wink

Offline

#8 2002-11-13 03:37:14

scottro
Member
From: NYC
Registered: 2002-10-11
Posts: 466
Website

Re: ?

I think, knowing all the work you do in supporting Arch Linux, that there is very little that could put you in a bad light.  I understand your point--if you were able to figure it out then others should be able to as well. 

I felt that those who were saying the documentation is incomplete were also offering to fix it.

It's always difficult, when one is not talking, and hearing the tone of voice and viewing facial expressions to judge another person's mood, but I didn't feel that people were going crazy over the documentation, just discussing what they felt would be helpful additions. Maybe I'm more used to abuse than you are.  I also tend to be fairly slow to take offense. 

I didn't feel the discussion over the documentation was insulting--on the other hand, of course, it wasn't directed at me, and I might have been quicker to take offense were I part of the Arch Linux team.

I would most certainly say that your opinion, in regard to Arch Linux, should hold far more weight than mine.

Scott

Offline

#9 2002-11-14 00:46:32

mordantly
Member
From: Westside - CenCAL
Registered: 2002-08-16
Posts: 83
Website

Re: ?

without stepping on other peoples' toes

point taken. yeah i know im a pain in everyones asses and slow on the obvious meter.. so fur all u that i have offended: im truely sorry. i inadvertantly became a (possibly the) pin jammed in the spokes.


try to be a man and some day, you'll understand   -ccr
oh dont u worry.. ill be eating ur balls fur lunch tomorrow.   -Hugh "HughMan" Stahl
MoRdAnTlY [Mr. Wolf '91 - '11]

Offline

#10 2002-11-14 01:04:18

sarah31
Member
From: Middle of Canada
Registered: 2002-08-20
Posts: 2,975
Website

Re: ?

mordantly wrote:

without stepping on other peoples' toes

point taken. yeah i know im a pain in everyones asses and slow on the obvious meter.. so fur all u that i have offended: im truely sorry. i inadvertantly became a (possibly the) pin jammed in the spokes.

bah you just tipe funnie  tongue


AKA uknowme

I am not your friend

Offline

#11 2002-11-14 02:18:50

mordantly
Member
From: Westside - CenCAL
Registered: 2002-08-16
Posts: 83
Website

Re: ?

yay!!, its bash on MoRdAnTlY time. my favorite time of the year.  :?


try to be a man and some day, you'll understand   -ccr
oh dont u worry.. ill be eating ur balls fur lunch tomorrow.   -Hugh "HughMan" Stahl
MoRdAnTlY [Mr. Wolf '91 - '11]

Offline

#12 2002-11-14 02:43:03

scottro
Member
From: NYC
Registered: 2002-10-11
Posts: 466
Website

Re: ?

Well, shoot, EVERYONE bashes on Southern CA.  smile

Anyway, a pacman -sS indicates that ispell is a package so we all have no exuse. --err, excuse, even. 

Scott

Offline

#13 2002-11-15 02:17:11

mordantly
Member
From: Westside - CenCAL
Registered: 2002-08-16
Posts: 83
Website

Re: ?

is my wolf sense tingling here?? cant we west coast - east coast guys just get along here??


try to be a man and some day, you'll understand   -ccr
oh dont u worry.. ill be eating ur balls fur lunch tomorrow.   -Hugh "HughMan" Stahl
MoRdAnTlY [Mr. Wolf '91 - '11]

Offline

#14 2002-11-15 02:47:45

scottro
Member
From: NYC
Registered: 2002-10-11
Posts: 466
Website

Re: ?

Heh, on my part, it's just envy--you have some of the most beautiful beaches in the world and it's getting cold here.  I wish I was there.   smile

Boy, have we wondered totally off-topic--that's one of the nice things about arch being small though. When it takes off, which I suspect is only a matter of time, we'll look back fondly at how we could ramble all over the place--when it gets popular, people will be shouting at us to stay on topic. 

Scott

Offline

#15 2002-11-15 12:34:30

dunbar
Member
From: Central New Hampshire USA
Registered: 2002-08-14
Posts: 106

Re: ?

apeiro wrote:

I agree wholeheartedly -- Arch needs more documentation.  The little we have was written by me and probably doesn't cover all the obvious points.

How does one go about documenting something?

Offline

#16 2002-11-16 02:26:00

mordantly
Member
From: Westside - CenCAL
Registered: 2002-08-16
Posts: 83
Website

Re: ?

Heh, on my part, it's just envy--you have some of the most beautiful beaches in the world and it's getting cold here. I wish I was there.

i agree 100 percent.. including the plentiful hotties. but i envy u too fur some things such as snowy weather to go skiing and all that schitt ive never gotten arround to.

How does one go about documenting something?

well, when u stuble across a situation, like the heated lilo config problem than one needs to write a summary up on the situation and how to correct the problem so it becomes a tool of use not destruction.


try to be a man and some day, you'll understand   -ccr
oh dont u worry.. ill be eating ur balls fur lunch tomorrow.   -Hugh "HughMan" Stahl
MoRdAnTlY [Mr. Wolf '91 - '11]

Offline

#17 2002-11-16 03:12:42

scottro
Member
From: NYC
Registered: 2002-10-11
Posts: 466
Website

Re: ?

Not too much skiing in Manhattan actually.  smile

Documentation--I'd say too, that if you're trying to write some, explain it clearly. At present yes, Arch isn't aimed at the novice, but actually, it's an easier install than say, Debian, and probably easier than Slackware--sure takes a lot less time, anyway.

Also, if you are going to try to write documentation, keep in mind that trivial though it may seem, one should try to use proper spelling and grammar. I've seen documentation for some other small distros, (sad to say, written by an American college student) full of typing and spelling errors, and personally, I felt it gave a bad impression of the distribution.

At present, judging from what has been posted in this thread, any documentation will be welcome.  As Arch becomes more popular, it may have to be explained more clearly.  While I don't think it should include a treatise on disk partitioning, for example, perhaps a link to the partitiioning section of the installation howto. 

FWIW, I co-moderate a list aimed at the Linux novice, and have put together a faq for it--it might give an idea of what the novice asks.  Anyone interested can have a look at
http://home.nyc.rr.com/computertaijutsu/linfaq.html   My site (same url without the linfaq part at the end) is listed as a useful link on the Gentoo forums, which might or might not mean anything. Interestingly enough, a lot of the time, it's simply a matter of explaining things a little more clearly than do the man pages.  For instance, although being far from an expert on using Japanese in Linux and FreeBSD, it seems that some consider me an authority-yet, if you look at the page about using Japanese in Linux and FreeBSD you'll see that every bit of information there came from someone else.

Scott

Offline

#18 2002-11-16 16:09:41

Arielext
Member
From: Amersfoort, the Netherlands
Registered: 2002-08-12
Posts: 362
Website

Re: ?

Putting all information together in an easy to read way is an art. Not many can do that. I know for sure I can't, don't write much help/howto's for my own programs.

Since a few weeks a German guy is helping me out with the documentation of one of my programs, and since then the populatiry (downloads) doubled.

ghehe now their up to 4 a day wink


apt-get install arch

Offline

#19 2002-12-29 11:12:50

scottro
Member
From: NYC
Registered: 2002-10-11
Posts: 466
Website

Re: ?

Yes, the forums are good, as are their mailing lists--and their irc channel can be helpful.  It's also a fun one--though I seldom use Gentoo these days, when I'm just wasting time, I hang out on their irc channel (my other favorite hangout is #freebsd on us.undernet.org

Gentoo's documentation has been simplified--when it first came out, there were only a few people using it and they were all experienced. As it became popular, it became more necessary to change their documentation for the newcomer to understand it.  The mailing lists began getting tons of questions that were covered in the faqs--this isn't a putdown of newcomers, it's just that when one is new, they don't know where to go to look for information.  The more experienced folks knew to read faqs first.


CUPS to me is an example of poor documentation.  They start off with too much background material--95 percent of the users just want to know, how do I get this to work. They include a CUPS howto in their docs--it consists primarily of telling you how to collect error messages to send to a mailng list.  If they put in the main part of the documentation, do X Y and Z, they could save a lot of people a lot of time.

I have some pages written when I was just learning--I sometimes look at them and think, oh, i should rephrase this or rephrase that--but I leave them, because the way I wrote them then makes them, I think, more helpful to the newcomer.  I go into explanations that I would probably leave out now, because they have become second nature. It is difficult, the more experienced you get, to realize what the newcomer goes through. I maintain a faq for several newcomer oriented Linux mailing lists.  I finally had to put in the question, "How do you get to the command line?"  People, when they first start, especially if they begin with newcomer oriented distributions, sometimes don't know the most basic things.  There's no sin in this, they have to learn. 

Ok, I'm done. smile

Scott

Offline

Board footer

Powered by FluxBB