Date: Mon, 14 May 2001 21:42:18 +1000 From: "Doug Young" <dougy@gargoyle.apana.org.au> To: "Sue Blake" <sue@welearn.com.au>, <freebsd-docs@FreeBSD.ORG>, "Rahul Siddharthan" <rsidd@physics.iisc.ernet.in>, "Kathy Quinlan" <katinka@magestower.com>, "N6REJ" <n6rej@tcsn.net> Subject: Re: (was) I'm leaving, now something like "anti official docs rant" :) Message-ID: <004901c0dc6a$ef1d1ac0$0300a8c0@oracle> References: <002b01c0db54$e0febaa0$5599ca3f@disappointment> <20010513171444.E26123@welearn.com.au> <00f401c0db7e$ff3ca2a0$fe00a8c0@kat.lan> <20010513122623.I97034@lpt.ens.fr> <20010514084709.A68348@welearn.com.au> <024b01c0dc05$b1314fc0$0300a8c0@oracle> <20010514103623.B68348@welearn.com.au>
next in thread | previous in thread | raw e-mail | index | archive | help
> The problem we have is that the people with the skills to execute > these good ideas, either don't contribute them to our docs (and > we're left with a volunteer staff of hard working Klingons trying > their very best), OR, they go off and do their own thing somewhere > else, which is great to have but fails to enrich the FreeBSD docs > in any way. > Well this is the second time I've subscribed to the docs list. Last time I gave up on it after a few months because I hadn't comprehended even one posting. It appeared quite obvious at the time that the inhabitants were only interested in waffling on about docbook or other esoterica rather than producing documentation meaningful to those who need it. I'm quite prepared to provide my Pedantic FreeBSD material, providing its not turned into something like the existing man pages .... the vast majority of which are totally incomprehensible to all but the experts. > Like so many things round here, we have lots of people ready > to jump up with good ideas, even more people weeing themselves > with excitement at the chance to code the infrastructure, but hardly > a soul to do the actual work. This applies to FreeBSD doc ideas > as much as it does to support ideas. "If you build it they will come" > is a naive view does not work for support/docs, but it has been a > popular pipe dream for the several years that I've been watching. > Better docs/support requires supply of prose, not code. > > Anyone who doesn't want a precious word of their prose altered > will have to do it some other way, of course. And there are other > reasons why some people keep their docs sepaparte from the FreeBSD docs. Certainly true ... if the intent of the docs fraternity is to turn everything into unintelligible verbiage as unfortunately appears to be the case. I made a comment earlier about the lack of any form of diagram / graphics / screenshot. Whilst it may be the case that nobody has thought to provide such (as you infer), but that seems beyond belief to me ... surely every adult on the planet has heard about "a picture tells a thousand words". Maybe I'm just cynical, but I have this feeling that there is an unwritten commandment "Thou shalt not allow things that make it straightforward for newcomers". An example that comes to mind is the age old issue of ppp configuration that causes untold headaches for 90% of converts from other religions. That ppp_conf.sh shell script that fixes the thing in 20 seconds flat has been lurking around the place since before JC played fullback for Jerusalem, but where is any mention of it found in official docs ?? Surely if documentation is meant to show people how to do stuff its reasonable to expect something as significant as this to rate a mention ?? Theres undoubtedly a million other comparable things out there someplace but the only way to discover them is by accident. > But in general, we need people contributing to docs if there is going > to ever be any improvement. And we need bums on seats and text on file, > way way way before we need more should-be and should-be-nots and code. > Thankfully its not quite as bad in the FreeBSD encampment as in the linux one, where one religiously checks for a new kernel every morning before breakfast, however I do agree that "we need bums on seats and text on file, way way way before we need more should-be and should-be-nots and code" > > > Where I started with this thread was trying to discover if its > > reasonably feasable to write a step_by_step HOWTO about X-windows. > > Please, please do! And please do it as part of the FreeBSD Doc Project > if you can. Then after it's done, you will become a role model who has > found an omission and gone on to correct it, and others might follow. > Well I did expect at least some response to my query about "what videocards typically work properly all the time", but the deafening silence so far suggests that the issue is somewhat of a yawn for the regulars. I'm not inclined to stuff around ad infinitum with X documentation if nobody has the interest to answer a question like that ..... its certainly not a matter of earth shatttering importance to me & I do have plenty of productive things on which to spend my time. Which reminds me I'd better get working on a talk about the Pedantic FreeBSD / use of the o/s as a gateway / router on cable / DSL connections / etc I've been "volunteered" to give to the Ausbug folk on Thursday evening. One never knows ..... might even convert a few from one or other of those other major religions :) To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?004901c0dc6a$ef1d1ac0$0300a8c0>