Date: Mon, 14 May 2001 12:11:58 -0400 From: Jim Mock <jim@FreeBSD.org> To: Doug Young <dougy@gargoyle.apana.org.au> Cc: freebsd-doc@FreeBSD.org Subject: Re: (was) I'm leaving, now something like "anti official docs rant" :) Message-ID: <20010514121157.A436@guinness.osdn.com> In-Reply-To: <004901c0dc6a$ef1d1ac0$0300a8c0@oracle>
next in thread | previous in thread | raw e-mail | index | archive | help
[ Cc list trimmed.. ]
On Mon, 14 May 2001 at 21:42:18 +1000, Doug Young wrote:
> 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.
Erm, "waffling on about docbook" is part of what this list is all about.
It's what the documentation project uses to create the docs. This is
what the handbook has to say about this list:
freebsd-doc Creating FreeBSD related documents
Talk about DocBook is certainly within the scope of this list.
The handbook's goal is to be a technical reference. That it is. If you
are expecting it to be a newbie-hand-holding walkthrough type document,
you will be disappointed. It's not one, and nor is it meant to be in
its current incarnation.
This once again brings up the topic of a "New Users Handbook". I
started work on this last year at USENIX (almost a year ago now), but
due to a lack of general interest and a lack of time on my part, I
haven't touched it since (as a matter of fact, I'm not sure if I even
still have it). If you're wondering what I'm talking about, take a look
at the -doc mailing list archives from June-July of last year.
I agree that this needs to be done. Unfortunately, I have a real job
and a life that takes most of my time these days, and more often than
not the last thing I feel like doing after I get home from work is
sitting in front of a computer.
> > 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.
Patches and contributions are welcome. What gives you the right to rip
into the documentation project when you haven't contributed anything?
Frankly, we have enough armchair generals out there and need some people
to start writing instead of complaining. This is an open source
project. If you don't like something, *YOU* have the ability to submit
changes to make it better.
If you don't like the way the doc project does things, contribute
somewhere else. I'm always happy to receive articles for the FreeBSD
'zine, so stop complaining and start writing :-)
> 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".
Support for images was only brought into the tree not that long ago.
Again, patches and contributions are welcome.
> 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".
Not only are you cynical, you're totally off the mark. As I said
before, the handbook, as it exists right now, is not meant to be a
newbie guide. It is meant to be a technical reference, and it does
that quite well.
> 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.
What is ppp_conf.sh? I've never heard of it until I read your message.
My guess is that nobody has ever mentioned it on this list, and nobody
took a few minutes to write up something about it and send a PR so
mention of it could be added.
> > > 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.
The issue is not a FreeBSD issue, it is an X issue. FreeBSD doesn't
really care what video card you have in your system, however, X does.
There is a list of supported cards on www.xfree86.org. Using a card in
the list ensures it will be supported.
> 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.
See above. You're looking in the wrong place for the answer to your
question.
> 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 :)
Good luck with your talk :-)
- jim
--
- jim mock <mij@osdn.com> - O|S|D|N - open source development network -
- http://www.freebsdzine.org/ - jim@freebsdzine.org - jim@FreeBSD.org -
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?20010514121157.A436>