From owner-freebsd-doc Sun Nov 1 10:14:21 1998 Return-Path: Received: (from majordom@localhost) by hub.freebsd.org (8.8.8/8.8.8) id KAA11908 for freebsd-doc-outgoing; Sun, 1 Nov 1998 10:14:21 -0800 (PST) (envelope-from owner-freebsd-doc@FreeBSD.ORG) Received: from vedanix.welearn.com.au (vedanix.welearn.com.au [203.35.200.140]) by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id KAA11901 for ; Sun, 1 Nov 1998 10:14:16 -0800 (PST) (envelope-from sue@vedanix.welearn.com.au) Received: (from sue@localhost) by vedanix.welearn.com.au (8.8.8/8.8.8) id FAA10959; Mon, 2 Nov 1998 05:21:37 +1100 (EST) (envelope-from sue) Message-ID: <19981102052137.50161@welearn.com.au> Date: Mon, 2 Nov 1998 05:21:37 +1100 From: Sue Blake To: "Jordan K. Hubbard" , Sean Kelly Cc: Nik Clayton , doc@FreeBSD.ORG Subject: Re: RFC: Handbook reorganisation Mail-Followup-To: "Jordan K. Hubbard" , Sean Kelly , Nik Clayton , doc@FreeBSD.ORG References: <363A1E89.DFEC36A0@plutotech.com> <18181.909783311@time.cdrom.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.89i In-Reply-To: <18181.909783311@time.cdrom.com>; from Jordan K. Hubbard on Fri, Oct 30, 1998 at 01:35:11PM -0800 Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org On Fri, Oct 30, 1998 at 01:35:11PM -0800, Jordan K. Hubbard wrote: > > Commenting on the new organization would be easier if we were to make a > > statement about what the intended goal and audience is: should the > > handbook be targeted to the lowest, most computer-unaware user possible, > > or is some familiarity with Unix assumed (for example)? This should be > > I think the only real answer to this question is: Yes. :-) > > The usual compromise approach is to make each chapter or section > follow the same basic flow pattern: You start with simple, 3-4 letter > words for the beginning and focus on "how to" style information and > then gradually get more technical until you're covering hacker-level > information at the end, capped by a further reading section that > really goes off into the deep end if one exists. That sounds great if the levels are clearly marked. Some chapters or sections will be mostly easy stuff and some will move to more advanced stuff very early. The start and stop signs need to be obvious. The first few times I read the Handbook, I read it from cover to cover without any idea that some was unnecessary. The "easy" bits were as incomprehensible to me as the advanced stuff so it seemed like it all had to be conquered before installing. > That way the novice users can just read as far as they need to and > stop (which their limited attention spam more or less guarantees > anyway ;) Ahem :-) their attention span is the same, i.e., they can take in exactly the same amount of new information as anyone else. It is difficult for doc writers to realise how many unfamiliar concepts can be crammed into a single sentence which sounds like a single point to them. Some novices study on anyway, and get so fed up with the effort (not knowing they can stop) that they never actually install the damn thing. > whereas the pros can skim the beginning and only start reading > seriously at the point where the information density seems high > enough. Yes, make them wade through too much boring stuff and they won't bother reading what we wish they would read either :-) I like Nik's new outline. It fits my perspective a lot better than the old. It will still need clear travel guides for different kinds of users, whoever we decide they are. Here's some brainstorming in case any is helpful... nothing concrete, sorry, just a perspective for now. I'd like to be able to pick up the handbook and instantly find what an inexperienced new user needs without much searching, and get that only to the level required for now (with links to more info of course) and in a sequence that resembles the order in which it can be used. The stuff that leads to "Look Ma, I'm _using_ FreeBSD" is critical. Things like: 1 How to get FreeBSD (options, pros and cons) 2 Very basic installation instructions, but including puzzles like - how to name and number the machine - lots on how to do an FTP installation (easier to do than it seems) - whether/how to install what packages at that time* - how to recognise when the installation has finished and if it worked - links all along to more installation info in case of trouble 3 Getting around from the shell prompt (WTF is a shell?); shutdown 4 Using ee for now, and mention better options for later 5 Anything that must be done or checked right after installing (using 3&4) 6 Installing the GUI window thing (oh, it's called X? it's not freebsd?) 7 Using X (how to get out, resolution, how the mouse works for copying, etc) 8 Connecting to my ISP (bugger the jargon, that's what I want to do) 9 Installing more packages (use packages or ports? why? how?) 10 Misc orientation stuff: - Things happen by themselves, like find at 2am, atrun; it's OK. - Locate doesn't work until Saturday; what do those root messages mean? - Getting more ttys and mounting (extended) DOS partitions They're all first day need to know topics for, e.g., Microsoft refugees working alone from home on their first FreeBSD system, and most of it's already in there somewhere. It can be too hard to find these topics from the contents unless you know what their section would be classified under. For example, I wouldn't have expected to find the windowing GUI thing under "Applications". Better organisation will help a lot but an additional read-these-first list might still be necessary. As you point out, it's important to tell people not only where to start, but also where to stop. One way of doing this is to use a very brief overview of a topic in point form, marking the essential newbie information for first time reading. Another is to present a guide to first use of the handbook, and yet another is to mark the actual pages. (Do people still hand out those bibles with lots of passages underlined for lazy converts with short attention spans? That's the approach.) If you don't tell newbies what to read, you take pot luck; if you don't tell them what *not* to read, they'll try to read it all then give up completely. We never hear from these people, but others do. It's starting to sound like I'm looking for a separate clueless newbies document, but no, I'd see that as counterproductive. It should all be mentioned in the one spot, with pointers to lots of tutorials for even more in depth easy treatment, but without assuming the reader has enough experience to choose what to read when. Most people are really new at some of this and want more advanced info on some other aspects, so it's convenient to have it all together; everyone starts with the handbook. And the handbook must be readily available in a recognisably Microsoft-friendly format if they are to read it before installing, and it would be nice if there was some easy way to identify and print just the first-needed sections from Microsoft, because that's what people will be trying to do with it. (Think about it: col -b is absurd) You can keep the stuff about allowing people to dial in, networking, firewalls, quotas, window manager choices and config, and other hacker stuff for later reading, but please do include everyone's skills under the "contributing to FreeBSD" heading, however humble they seem. Good habits start early. It might be useful to take a similar look from several other perspectives, and see how many of them can be accommodated in the one document because of the improved structure. The picture I've painted here must look awful to people who basically know what they're doing. Yes, I will be prepared to put my pen where my mouth is if there are holes to fill. For now I'm just throwing ideas around for criticism. * In a few weeks I'll be trying to get around this by bundling a small starter set of packages together that will suit those without a clue, together with some config files and doccos similarly aimed. I'm still trying to get a clue myself though :-) -- Regards, -*Sue*- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message