From owner-freebsd-advocacy Fri Apr 2 15:49:38 1999 Delivered-To: freebsd-advocacy@freebsd.org Received: from mta1-rme.xtra.co.nz (mta.xtra.co.nz [203.96.92.1]) by hub.freebsd.org (Postfix) with ESMTP id D766C15057 for ; Fri, 2 Apr 1999 15:49:29 -0800 (PST) (envelope-from junkmale@pop3.xtra.co.nz) Received: from wocker ([210.55.164.76]) by mta1-rme.xtra.co.nz (InterMail v04.00.02.07 201-227-108) with SMTP id <19990402235025.JLAH5454377.mta1-rme@wocker>; Sat, 3 Apr 1999 11:50:25 +1200 From: "Dan Langille" Organization: The FreeBSD Diary To: Nocturne Date: Sat, 3 Apr 1999 11:49:51 +1200 MIME-Version: 1.0 Content-type: text/plain; charset=US-ASCII Content-transfer-encoding: 7BIT Subject: Re: The FreeBSD Installation Guide Project [Was: Re: FreeBSD Advocacy] Reply-To: junkmale@xtra.co.nz Cc: advocacy@FreeBSD.ORG In-reply-to: <37054AEC.B908B436@uswest.net> X-mailer: Pegasus Mail for Win32 (v3.01d) Message-Id: <19990402235025.JLAH5454377.mta1-rme@wocker> Sender: owner-freebsd-advocacy@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG On 2 Apr 99, at 14:55, Nocturne wrote: > Most excellent, thanks, but I like Donald's idea of having all the > doc projects hosted at the same site.  Fair enough too. > > > 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. > > > > All of this is already in The FreeBSD Diary. Have a look and see if > > it's up to scratch. > > The information is all well written, and simple to understand for the most > part, but you're explaining what you did instead of showing the steps. > Plus, it's making assumptions that the reader already knows how to get to > the files and information you refer to: > > You say something like, "I put these lines in /etc/rc.conf..." > My original idea is to have it written like, "At the # prompt type... go > to this line in the file and type..." Unless folks think it would be too > dry for newcomers (which is why I want newcomers to be the proof-readers). Fair enough. I know think we're aiming at two different audiences. or perhaps I've misunderstood your intentions. There are some assumptions I make regarding the reader. Not all of those are stated. Perhaps all that is needed to make the Diary material more suitable for the installation guide is, for example, a separate section on how to edit a file. > It should be understandable by someone with no unix skills at all. > Imagine a newbie installing FreeBSD for the first time. Part of the > installation requires them to edit a .conf file. The CFBSD or > Handbook says which file to edit and explains what they have to > change, but says nothing about the commands they have to do to find > and open the file. CFBSD has the vi man page, but how's the newbie > going to know it's there and what it is unless there's a reference to it? Yep. I still reckon this could be covered by a section on "how to edit a file". I don't think you intend the the Installation guide will be step by step for every file that needs to be maintained. What we need is a short introduction to Unix commands. We can make use of existing documents. I have a website section titled "Stuff for Newbies" which might be a good starting point. I think that would elminate both repetition and boredom for the reader. -- Dan Langille The FreeBSD Diary http://www.FreeBSDDiary.com/freebsd To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-advocacy" in the body of the message