From owner-freebsd-doc Sun Apr 4 23:51:55 1999 Delivered-To: freebsd-doc@freebsd.org Received: from phoenix.welearn.com.au (phoenix.welearn.com.au [139.130.44.81]) by hub.freebsd.org (Postfix) with ESMTP id 15B9714FAD for ; Sun, 4 Apr 1999 23:51:45 -0700 (PDT) (envelope-from sue@phoenix.welearn.com.au) Received: (from sue@localhost) by phoenix.welearn.com.au (8.9.1/8.9.0) id QAA05100; Mon, 5 Apr 1999 16:49:34 +1000 (EST) Message-ID: <19990405164928.40818@welearn.com.au> Date: Mon, 5 Apr 1999 16:49:28 +1000 From: Sue Blake To: Nocturne Cc: doc@freebsd.org Subject: Another Installation Guide [was: FreeBSD Advocacy] References: <37052E56.D243D4F6@thuntek.net> <37053C70.A99BEB29@uswest.net> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.88e In-Reply-To: <37053C70.A99BEB29@uswest.net>; from Nocturne on Fri, Apr 02, 1999 at 01:53:52PM -0800 Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org 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