Date: Sat, 3 Apr 1999 11:49:51 +1200 From: "Dan Langille" <junkmale@xtra.co.nz> To: Nocturne <dpilgrim@uswest.net> Cc: advocacy@FreeBSD.ORG Subject: Re: The FreeBSD Installation Guide Project [Was: Re: FreeBSD Advocacy] Message-ID: <19990402235025.JLAH5454377.mta1-rme@wocker> In-Reply-To: <37054AEC.B908B436@uswest.net>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990402235025.JLAH5454377.mta1-rme>