On Sat, 26 Nov 2005 16:54:04 -0500, Chris Zakelj <[EMAIL PROTECTED]> wrote:
>J.C. Roberts wrote: > <snip> >>I'm just a normal user who doesn't contribute a great deal to the >>project, so there is a *HUGE* difference between me and the people who >>actually have both the expertise and dedication needed to write quality >>code to improve the project. -To them, I'm just another loud mouth >>chatting away on misc@ rather than doing something more productive. >> >>Kind Regards, >>JCR >> >I'm going to take this thread for what I think it is... the old guard >telling us youngin's that our efforts are appreciated, but we've got a >bit more to learn about how things work, and how to write good >documentation, before we're really ready to jump into these things the >way we have been lately. I've noticed a decent drop in the number of >"How do I get PPPoE working" and "How do I get Apache+MySQL+PHP working" >questions on the list, which is what prompted Daniel to create >openbsdsupport in the first place, so in a way, we've been successful in >what we set out to do. I may seem overly critical in debate but I still believe the work of Daniel Ouellet and the HOWTO writers has been a worthwhile experiment. Though it has opened the door for the blind leading blind, only by experimenting with new ideas will one be able to prove or disprove their validity and in the process, you might learn something unexpected. Do you really think the UNIX companies of old "wasted" expensive developer resources writing documentation? -Nope, the job was farmed off to the new and inexperienced cheap labor which usually resulted in worthlessly incorrect docs. Yes, in a sense you could say the "old guard" have witnessed the results of this experiment before and watching history repeat itself, brings back less than pleasant memories for those who have already lived through it once. >That said, it's about time I revisited the >userland PPPoE doc I wrote a while back one last time and mark it as >obsolete, especially in light of the amazing pace that Can has been >keeping on the kernel interface, and how user-friendly the pppoe(8) >manpage is. > As Otto wisely said: |Man pages are the authorative documentation. If you find them lacking, |help us in making them better. It is possible your PPPoE HOWTO may have helped in some way to the creation of more user-friendly documentation in pppoe(8). On the other hand, if you had set out with the goal of making pppoe(8) more user-friendly by working with others, the end result you wanted may have been reached a lot sooner. Look at UNIX history a bit. There are moments when I'm still just floored by the fact I have a completely free UNIX operating system, including source code and docs which I can use on whatever machines I want for as long as I want. Try paying per minute for CPU time on a multi-user system for a few years and you'd be floored too. Back in the bad/good old days of commercial UNIX, the odds of a system developer inviting you to work with them to produce better documentation was only a dream even if you were a genius. The "youngin's" as you call them, have an opportunities that the "old guard" never had. Different people do things for different reasons and many people get satisfaction from putting their name on the things they do. The recent flurry of HOWTO's is really no different and at least some of the authors revel in the "look-at-me" factor far more than they aspire to produce correct documentation. You may not get to toss your name in lights if you work with one of the knowledgable people who have given you an open invitation to help improve the docs, but it is a decision you'll need to make on your own and for your own reasons. If the contributor is more important to you than the contribution, then you're already sunk. On the other hand, when a five year old child very sincerely says, "look at me, I'm helping," while they are really just getting in the way, the right thing to do is show a bit of patience rather than stomp on their parade. Yet when said child is probably in his teens or twenties, well, my tolerance fails in a hurry, in spite of all his supposedly sincere and good intentions. I'll immediately start questioning his intelligence, his knowledge, his experience and his motives. Maybe he just needed to run a well known, age old, experiment for himself to learn what can be learned from it. Then again, maybe not but either way, time will tell. >Call me a masochist, but I sorta like being clobbered over the head by >Theo and his team. I learn more about how to do things right that way >than I ever have by picking up a book or guessing at what a doc was >trying to tell me. > Funny, I was busy writing this same exact thing in another reply when you posted this. ;-) Kind Regards, JCR
