Date: Mon, 5 Apr 1999 16:49:28 +1000 From: Sue Blake <sue@welearn.com.au> To: Nocturne <dpilgrim@uswest.net> Cc: doc@freebsd.org Subject: Another Installation Guide [was: FreeBSD Advocacy] Message-ID: <19990405164928.40818@welearn.com.au> In-Reply-To: <37053C70.A99BEB29@uswest.net>; from Nocturne on Fri, Apr 02, 1999 at 01:53:52PM -0800 References: <Pine.SV4.3.96.990402153139.28286A-100000@pegasus.cc.ucf.edu> <37052E56.D243D4F6@thuntek.net> <37053C70.A99BEB29@uswest.net>
next in thread | previous in thread | raw e-mail | index | archive | help
On Fri, Apr 02, 1999 at 01:53:52PM -0800, Nocturne wrote:
>
> This is something that I could actually work on, so here I go:
>
> FreeBSD Installation Guide Project
>
> We need:
> Web space for a home site and a person (or two) to make the pages.
> People with working knowledge of how to setup a basic LAN (NAT,
> routed/gated, DNS, ipfw, ppp) to work with dialup or DSL/cable.
> Proof-readers to make sure the information has as few knowledge
> pre-requisites as possible.
> Users who are very new to either FreeBSD or unix in general to read
> through the instructions and point out anything we miss or take for
> granted.
> (anything else?)
>
> We ask:
>
> What topics do we need to cover?
> Do we really need any printed man pages?
> What information can be accessed from the CD prior to install?
> What of that information is printable?
> (any other points to address?)
I see this has generated a long thread that I might not have totally
caught up with, nevertheless I'd like to make a few cynical remarks.
I have seen scores of installation guide attempts come to nothing, a
few reach a point where they are available but considered "unfinished"
by their authors for months or years, and several actually finished. I
don't like any of them. I have no reason to believe that the next one,
or the one after that, is one I will like any better.
In particular, those ideas which depend on enlisting volunteers to work
with someone on their pet idea are famous for not getting off the
ground. Hardly any new FreeBSD user hasn't said "gee, I could write a
better installation guide" so it can be hard to sell them on the idea
of working with someone else's ideas. See the first 2-3 months of the
freebsd-newbies archive (a year ago) for many spectacular
illustrations, but grab a tissue first.
If you, or anyone else, wants to write YAIG please go right ahead. The
more finished attempts the better. Just don't be too surprised if those
around you are skeptical until it bears fruit. Once we've got a few
dozen of these "Ha! Even I could do better than that!" documents, we
might start to see a few that are indeed better, and from that new
perspective we might start to get a better idea of what is required to
cover everyone's needs. I'm not holding my breath, but it would be
very nice to see.
Having decided to proceed, you've got a big choice to make.
Do you want this to be an independent effort, or a FreeBSD project?
There are pros and cons with each, but you can't have it both ways.
If you want it to be a FreeBSD project, to some extent that will allow
you to draw on the human and other resources of the community,
especially the Doc Project people. You can also give it a FreeBSD Doc
Project name if it's functioning as a project. The cost is that the
work you do with documentation as part of the central FreeBSD effort
must fit in and support the existing Doc Project. That doesn't mean
that it can't amplify it in new directions, but if you want the support
of the team you gotta be prepared to play their game a little
sometimes. Of course your goal would be to put effort into the FreeBSD
Project, not dissipate its resources. The work you put in will help
many other FreeBSD users and improve the standing of the Doc Project.
If you want to do it external to the FreeBSD Project, you have total
freedom. It's a bit hard to call it a FreeBSD project if it's not, but
you can write whatever you like, however you want to, choose who works
with you and even set out what they are to do. Human and other
resources will be offered to you by individuals from the community, but
external to the FreeBSD Project itself, on the basis of how well you
are regarded, how clear your ideas are, and how easy to work with you
appear to be. What's more, if you retain your position as leader
throughout you can put it up on your own site somewhere as your own
accomplishment. If it's good you might even manage to get a link to
your site from the FreeBSD web site, and if it turns out not too good
or incomplete, ah, hell, you can put it up somewhere anyway. The work
you put in will help many other FreeBSD users and make you look good.
In the past I've gotten pretty hot under the collar about people going
off blowing their own little trumpets instead of working with the Doc
team, but in this particular case I hold the opposite view. I predict
that the next several attempts at an installation guide still won't cut
it, and I'd like to see a fair bit more experimentation and testing
before settling on what to have in the Handbook long term. That doesn't
mean that the Handbook can't be improved or rewritten in the meantime,
but it's a lot easier to ditch and replace a Handbook entry that was
written by "Doc" than one which has a heavy investment of some
individual's name or viewpoint.
Go do your thing, any way you can, any way you feel like, for exactly
as long as you feel like doing it. If you need the help of others,
you'll get it if you're offering them what they need in return.
Whatever you end up doing will be worthwhile and others are bound to
learn from your experience in many ways. Just set out with very clear
plans, and make sure it has a good chance of becoming very finished.
Good luck!
--
Regards,
-*Sue*-
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?19990405164928.40818>